in reply to On comments
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.