WEB Advent 2008 / Commenting on Commenting

Everyone knows the standard programming mantra “Document your code” (although some people seem to still not follow it), but today I want to talk specifically about three types of documentation that can exist for a project, and how each of them is important.

When you mention commenting to a PHP programmer, the first thing that comes to mind for most are PHP DocBlocks. DocBlocks are a great system for providing consistency in your comments and for seeding auto-generated documentation. However, DocBlock by its nature, is based around documenting the API of particular functions, classes, etc. To that end, it’s an amazing system.

The problem is that documenting the API—function parameters, the purpose of a class, and other similar items—is only one of three types of documentation that are needed. I’ve found too many PHP programmers that are in the habit of writing DocBlocks, and assume that their “requirements” to comment and document are fulfilled.

This is far from the truth.

Firstly, within a larger product there is a higher form of documentation that is needed. For lack of a better term, let’s call this “implementation” documentation. Basically, what I mean is documentation that doesn’t just say, “Here is a class you can use; here are its methods.” This documentation explains the whole process of how, within your project, those classes are meant to be used.

This type of documentation can range from best practice information to simply explaining how common programming tasks are to be done. Having documentation for a dozen classes doesn’t help a future programmer if there is nothing explaining how they are supposed to chain these classes together to perform tasks. It’s also less useful if it lacks an explanation of what information is saved in the session, versus in a datastore, and how they relate to each other, as well as what helper functions should be used to access the data.

Now, we are left with the final type of documentation, which seems to be the most overlooked by programmers who rely on the DocBlock crutch: honest-to-goodness inline comments.

Inline comments that explain what the actual lines of code are doing are absolutely vital to enabling other programmers to pick up your code, understand it, and augment it. Yes, you may think that your 12-line function is so simple that anyone can follow it, but realize that quite often your fellow programmers will not be planning on trying to fully understand every aspect of that function just so that they can fix a bug that it has caused. Good comments that explain what different sections of code are doing are absolutely critical to rapid debugging—they allow a programmer to scan the comments to immediately find the section of the code that they were looking for, without reading and understanding every line of surrounding code.

Everyone, of course, has their own definition of “how much is too much” when it comes to inline comments, and I don’t think there is a right answer. I once worked on a project where, by contract, we had to have one line of comment for every line of code. (They used software to remove all of the actual code, leaving only the comments, so that people could read what the code was supposed to be doing in regular English.)

One line of comment per line of code is perhaps overkill. Having to fulfill that requirement for so long, though, did get me into the habit of writing lots of descriptive comments, so I feel it was a great learning experience for me.

So, that being said, let me try to impart my own suggestions for making sure that you write good, descriptive comments:

  1. As you are coding, write a comment that explains the next step that you need to take, then write the code that performs that step (whether it’s a single line or 20).
  2. Try to imagine someone reading only the comments and ignoring the code. Would they understand what each section of code is doing at a high level? If aspects of the code have been overlooked, add another comment or two to describe them.
  3. Don’t be afraid to write a long, multi-line comment if there is a particularly complicated section of code, or if you had to put some serious thought into a problem. I would much rather read a 5-line description of why some code is the way it is than to see what appears to be a “silly” line of code that I might change (and break the application).

So, hopefully you’ve enjoyed this brief trip through the world of commenting. Whether you use PHP DocBlocks or not, do try to make sure that you have covered all three aspects of documenting your project:

  • Implementation—documentation that tells programmers where to start and how to accomplish tasks.
  • API—documentation that describes each class and function in detail.
  • Inline comments that explain the code itself.

Now everyone, repeat with me: “Comment your code!”

Other posts