Beginner's guide to writing comments?
- by Cameron
Is there a definitive guide to writing code comments, aimed at budding developers?
Ideally, it would cover when comments should (and should not) be used, and what comments should contain.
This answer:
Do not comment WHAT you are doing, but WHY you are doing it.
The WHAT is taken care of by clean, readable and simple code with proper choice of variable names to support it. Comments show a higher level structure to the code that can't be (or is hard to) show by the code itself.
comes close, but it's a little concise for inexperienced programmers (an expansion on that with several examples and corner cases would be excellent, I think).