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:
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:
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:
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:
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:
- Parameter descriptions. Do any of the parameters need explanation? Are only certain values allowed or disallowed?
- Error conditions. What happens when something goes wrong? Does the function return error codes, raise exceptions, etc.? Does it always leave the program in a valid state?
- Limitations. Are there cases that the current implementation doesn't handle?
- Performance guidelines. Are there cases where the function is really slow? Are there things the caller can do to make it fast?
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.