Solve The Real Problem

Discussions about professional software development with a focus on building real, solid, performing, reliable, monitorable large-scale online services in asynchronous C++. You know, good solid breakfast food.

Tuesday, April 20, 2010

Are we really still debating comments?

A colleague pointed me to a list of reasons why comments are bad (with a sigh):

They do not change with the code.
Only if you don't change them when you change the code, which is irresponsible. They're right there next to the code. They helped you remember the intent of the code (why it was trying to do something, and how it was going about it). If you don't update the comments for the next guy, or the next instance of you, you aren't finished the job.
A wrong comment is worse than horribly complex non-commented code.
This is an excellent reason to write proper comments and change them when the code changes. It is not a reason to omit them altogether.
A comment almost always expresses an absolute thing, where a well named variable or method can express an abstract concept. Comments can actually tightly couple your code. Take the example above where int i = 5 had a comment stating that 5 was the default. DEFAULT_PRODUCTION_WIDGET_COUNT communicates the same information, but at a higher level of abstraction.
This reasoning is flawed. The presented argument (via the example) is a false choice between comments and good variable names. Choose both.
Comments don’t show up in stack traces.
Stack traces are the poor man's error handler or log message. And besides, if a stack trace means something to you, you are familiar with the code and thus you have it and its commented intent.
Reading comments is optional. Reading code is mandatory.

Understanding the intent of code is mandatory. The vehicles for achieving that include reading the comments, whose primary purpose is to tell the "why" behind the "what" that is expressed in code.

This list sounds like rationalization for not doing the entire job, and not doing a good job. The presumption that one's code is so good, and so clear, and so well-suited to its purpose is naive and bordering on pompous, since it doesn't take into account the reality of multi-developer, multi-year, multi-site, multi-purpose, multiply-reworked and repaired code. Not commenting your code may be good enough if you are its only consumer, but otherwise, it's amateurish and a red flag. Stay away.