source | link

Comments are for who, when, why, assumptions, dependancies, and possibly how.

Who wrote this? Who do I go and bug if I have questions about it?

When did they write it?

Why did they write it? What was the business reason that they spent time writing code?

Why did they pick this approach and what other approaches did they reject, and why?

What assumptions did they make? What beliefs about the organisation did they hold?

What things are required to happen for this code to execute successfully? What libraries, objects, environments or other things is it dependent on?

What are the situations in which the code might fail and how does the code deal with those failures? How do I deal with them?

As for the "how", comments should only explain how the code works if it is complicated and hard to understand (and if it is then perhaps the programmer should have put more effort into simplifying it).

    Post Made Community Wiki by Greenstone Walker