The importance of writing comments while developing code

I just didn’t understand eighteen months ago. I had no clear understanding that developing a WordPress plugin was more than just the code.

Programming is also about writing good comments above the functions.

When I started programming, most of the original work was done in Coda 2 or some handy text editor. I even tried developing online while tinkering with a Chromebook. This was fine because so much code was copy-paste from online examples as well as discussion posts on XenForo or WordPress forums.

This type of cowboy coding just cannot stand the test of time, though. The results are a disaster of code strewn all over the place.

Eventually, my development environment grew to include MAMP, phpStorm, Xdebug, Query Monitor, and several other ways to debug a WordPress plugin. Now there is even version control.

This major change in development allowed me to rearrange code so that it made sense to me and helped me debug problems. Functions are in files named so it is obvious where to look. Option names are clear. Even class names and file names match.

My biggest regret, though, was not leaving notes in the code for myself to read later. As my knowledge has grown, I’ve slowed things down because I didn’t leave good notes and so I practically start over each time a file is opened.

PHPDoc: Easy To Write, Easy To Overlook

A PHPDoc block is easy to write in phpStorm: place the cursor above the function, type a slash and star then hit enter. The comment block is created. But it is not complete. And that was my mistake in focusing on the lines of code and not the comments. The PHPDoc needed much more information and so when I have returned to the code months later then my initial thoughts are well forgotten.

Example 1

I’ve spent several hours over the past two days looking at code in one particular file. My mind is boggled by the spaghetti that is on the page and I hesitate to make any changes. For example, after spending a few hours with one function, I realized that the array was following the WordPress comments database but without the newly added field created during the plugin activation. Anyway, I’ve learned the hard way that slight changes can have great rippling effects and so making any changes on this page is terrifying.

Example 2

Consider, for example, a new thread creation code written for a new version of XenWord. Four lines of good clean code replaced a meandering of repetitive code rife with errors. Since the end result was working (most of the time) then I didn’t want to touch the function until I could really understand how to improve the code. However, once the old code in the new thread creation function was replaced with the newer, cleaner code then an error popped up in another file — a file filled with terrible spaghetti code. A file I hate to even open.

Here I am now, wishing each PHPDoc was properly completed.

Example 3

Getting started with PHP is easy. Mastering PHP is another story. There are many ways to complete a task and it is really a decision that is made while developing to decide — switch or if, else?

There are also reasons to use a set of hooks or filters over other choices. For example, there are times to decide between transition_post_status, publish_post, or future_post. And if something isn’t happening as expected then it is good practice to leave a note in the code.

I knew 18 months ago that scheduled posts were not working properly in XenWord. I don’t use them so it made no difference to me. However, on multiple occasions I’ve tried to fix the code to get scheduled posts to fire a function. My notes were very poor, though. At one point I remember reading someone stating the date had to be included or the cron job wouldn’t fire. After spending hours, I can’t find that post. It would have been best to just include a link to it in the code. Even after posting on stackexchange a few times,  and trying their advice, scheduled posts don’t work. But my concern is that I haven’t left enough notes for myself.

The Best Formula

I’ve come to a few conclusions after spending the past two days tinkering with PHPDoc blocks.

• The purpose of the function.
• The date for any changes.
• Any TODO notes.
• Possible options available to change in the code.
• Include hook or action links to where to get more information.
• Include links to blog posts or articles with explanations for code.

These are just a few items needing updating in XenWord. It’ll take time but in the long run the practice should save time. After all, opening a file up and asking, “What was I thinking?” is a horrible feeling.