Code Documentation

At work I've worked with a lot of people who are either just out of College or still in College. There has been an interesting trend in their code's documentation: they like a lot of it.

I'm guessing that they were taught that code had to have comments and they were probably deducted points if they didn't have any. However, they weren't deducted points if they wrote bad comments and they weren't granted points if they wrote good comments. My guess is no one ever told them what the difference between a good comment and a bad comment was. So usually one of the first things I try to teach is what my guidelines for comments are.

1. Meta data is a bad substitute for good readable code
2. Write future proof comments. Don't write a summary comment that says what each step of your method will be. This is guaranteed to be out of date when someone else changes your method's code and forgets to update the comment. Now your comment is a lie.
3. Tell me what your methods, properties, or objects will accomplish for me. Don't tell me how to use them. I can determine how best to use it once I understand what it does.
4. Only current code matters, what the code did in the past is not important. Don't document history in your code files.
5. Add line comments if the line is confusing or needs clarification. If it's clear on it's own, don't clutter it up with a comment.
6. Break code into methods instead of using large or intricate commented sections.
7. The shorter the better
   

Two things drive all these guidelines:

1. The goal is readable code
2. Its better to read code than to read meta data
   

If your code isn't readable, you're going to be afraid to read it, and that's a problem because its better to read code than to read meta data (and comments are just meta data). Why? The meta data may be out of date, or it may not accurately represent the code. In the end, it doesn't matter what you think the code does, it matters what the code actually does. The best way to determine what it actually does? Read it. That doesn't mean you can get rid of all meta data, because you can't. But you can be very careful with what meta data you create and what content it contains.

The main purpose of summary comments is to clarify what code is meant to accomplish when the name may not be sufficiently self explanatory. This will help people (including you) figure out how they should use that code. If they want to really understand what it does, they'll have to read it, but if the summary and name are written well enough they should understand enough to take advantage of its functionality.

The main purpose of line comments is to clarify code that may be harder to understand for some reason. This could be to describe why something is necessary (like a hack). Or to explain the effect a line will have on a line somewhere else (like to cause a loop to break).

There are cases where you may need to not follow these guidelines, that's why they're guidelines. However, in most cases they've served me well and helped me produce cleaner and more easily understood code.