Comments in source code

Today I have been asked again, why we don't require comments in source code. We have discussed this issue a lot of times. Right now I feel, that I have to write my thoughts down, not to repeat myself in further discussions, kind of reuse, you know ; )

By the way, we do require comments on version revisions and you have to bring a beer, if you have commited changes without a comment.

Comments are part of documentation and that is why I would like to refer to very good essay on documentation by Scott W. Ambler. He is one of the few persons in software development community whom I respect very much.

One of his critical points says, that you can not trust documentation. Comments neither.

Here is an example:

// this method sums first and second parameters and returns the result
public static int sumTwoNumbers(int a, int b) {
    return a*b;
}

This creates a very serious implications on developing and maintaining documentation (source code comments in our case).

Here are reasonable arguments, why we should document(comment) our code?

1. Our stakeholders require that. Lets think, who is our stakeholders in case of source code comments? Mainly they are other developers and managers. They think, that after you leave the company, it will be easier for others to understand your code and your design decisions. I assure you, that if we follow simple rules: don't develop alone, practice test driven development and use meaningfull names, we will achieve even more, than only through commenting our code.

2. To define a contract model. This mostly is needed, then external organisations or groups are involved. Source code is so intimate thing, that we will not publish it to external organisations. If we need to invest into contract model development and maintainance, we'd better keep it separate from source code, thus comments should not be used for contract model describtion.

3. To support communication with an external group. The are other good ways to communicate your decisions through source code: unit tests and meaningfull naming. You should understand, that commenting is your option of last resourt and you should use it only if you feel, that source code does not communicate all details properly.

4. To think something through. Well, to use comments for thinking something through is kind of noncence for me, but use it, if you know how. Don't forget to delete it, after source code is ready.

Please, read Scott's paper through to get aquanted with questionable reasons for creating documentation and other important issues concerning effectivness of paperwork.