Re: On comments

[eyepopslikeamosquito]

I agree.

My rules for commenting (from On Coding Standards and Code Reviews) are:

• Correctness, simplicity and clarity come first. Avoid unnecessary cleverness.
• If you must rely on cleverness, encapsulate and comment it.
• Prefer to make the code obvious.
• Don't belabour the obvious.
• Generally, comments should describe what and why, not how.
• Remove commented-out code, unless it helps to understand the code, then clearly mark it as such.
• Update comments when you change code.
• Separate user versus maintainer documentation.
• Include a comment block on every non-trivial method describing its purpose.
• Major components should have a larger comment block describing their purpose, rationale, etc.
• There should be a comment on any code that is likely to look wrong or confusing to the next person reading the code.
• Every non-local named entity (function, variable, class, macro, struct, ...) should be commented.
• Don't optimize prematurely. Benchmark before you optimize. Comment why you are optimizing.
• Limit and explicitly comment case "fall throughs".

See also Perl Best Practices, Chapter 7, Documentation, which has some excellent advice on how to document your programs.