How to comment source code

Teamwork is so much different than having 1 programmer write code alone. The reason is, that in a team, source code is read so many times, that readability is much more important than how long time it takes to write the code.

I just ran across this link, where the author says, that if everybody comments, "others" get as much out of it as yourself. However, the main problem is not how much the individual programmer gets out of it - it's the team performance, that is important.

In order to optimize team performance, all members of the team should be able to have the best possibilities to edit all parts of the source code, and that requires comments.

My experience shows, that good comments are characterized by:

* They are automatable (for documentation, localization etc.)
* They don't take significant time to read
* They do not repeat information that you can read easily from the source code (don't write "This is function xxx which takes parameters yyy")
* They include important design decisions, and explain problems that the author spent time on, while programming.
* They document purposes and examples (in case of unit testing and some other cases, examples can be omitted)
* They document a group of source code lines, and not each source code lines.