Make Your Bed, Eat Your Veggies, and Comment Your Code

Every programmer knows they're supposed to document their code. Just like keeping your apartment clean though, documentation often gets put off until "later". Also like cleaning, it's easier to do documentation as you go, rather than in a big push at the end of the dev cycle. A pragmatic commenting style can go a long way to making this a reality. Below are some tips to make commenting less of a chore.

Agree on a format

To me, order and consistency make code look right. If you work this way too, it's a good idea to settle on a common format for your comments. A couple possibilities for functions:

//-----------------------------------------------------------------
/// YOUR COMMENTS HERE //-----------------------------------------------------------------

/**
 * ... OR YOUR COMMENTS HERE INSTEAD
 */

Both of these are doxygen compatible. The first has the nice property of indicating the maximum line length, which is good for consistency. It's a bit of a hassle to type, so you'll probably want to create a macro for it in your editor of choice.

The second format is easier to type, and less fussy about line lengths (good if you are also less fussy about such things). It's not quite as visually impactful, but good use of whitespace can fix that. Pick something that works for you, and stick to it.

Keep it simple

It's easy to get carried away when trying to come up with a coding standard. The trouble with getting too elaborate is if the standard creates too much work, the temptation to ignore it will be overwhelming. Short comments also minimize wasted effort when you change or delete a function.

My suggestion is that any standard should accept this as a valid comment:

/**
 * Sorts the objects in place in front-to-back order.
 */
void sortFrontToBack( SomeContainerClass& toSort )

The point here is that while you could add more detail, you shouldn't have to. A one-liner is much better than nothing at all.

Don't redundantly repeat yourself over and over again

You don't need to restate things that are clearly stated by the code. It's fair to assume that the reader of your code understands the programming language you're working in. Let's say you're documenting a function like this:

int getOrgreCount( Zone& queryZone )

The name of the function is obvious, don't put it in the comment. Explaining that the queryZone parameter is a reference to a Zone object, also redundant. Returns an int, redundant. Really, all you need to say here is something like:

/**
 * Returns the number of ogres in the queryZone, or -1 on error.
 */

On the other hand, if you're working in a loosey goosey language like Python, commenting on the expected type is a very handy thing to include in the docs.

Develop a mental checklist

Sometimes you stare at an undocumented function and think everything about it is so obvious that anything you write would be pedantic and useless. This happens a lot when the code is designed well to start with and uses informative names. To get past writer's block in these situations, develop a mental checklist of things that might be worth pointing out, such as:

By running though a list like this, you'll rarely be at a loss for words.

These tips will hopefully encourage you to tackle documentation proactively. Documenting code is part of being an organized professional, but it doesn't have to be a big chore. Most of the time, we're not building public APIs that need exhaustive documentation. Just leave your teammates and future-you some useful notes about what's going on in the code, and you'll soon be reaping the benefits of documented code.