Code Comments Aren't Evil

Stewart writes, "Comments Are Evil", most specifically, "Remember kids, comments in code are evil. They are wrong - or misleading at best".

Unfortunately, this is wrong advice.

Code comments can be misleading - they can do more harm than good. But I've seen both ends of the spectrum, the Ada-comment-every-line-describing-what-the-loc-does and the *nix kernel hacking idea of the-code-is-your-comments idea. Both are extremes and both are wrong, even though "the definitive record is the code itself".

Code comments should:

• state the functional intention of what the block of code is trying to achieve, not how it is achieving it;
• highlight any tricky gotchas for future maintainers; and
• identify any use of common algorithms or design patterns or similar so that someone trying to understand it may get a leg up.

Getting the level of commenting right is hard, especially if you haven't written much code, or if you are unfamiliar with the domain or the implementation language. But commenting done right can greatly assist yourself and others when you revisit that chunk of code - whether that be to find that heisenbug, or to add new functionality, or even just understand what you were trying to achieve back 3 weeks ago.

/tech/code | 11 Aug 2005 | #