The view I have developed about code comments is informed by years at the coal face of software development and re-enforced by what @unclebobmartin has to say about them in Clean Code, which I read last year and continue to refer back to.
Stale comments lie.
In my opinion, commenting code is the laziest way of expressing intention or semantics in code. Why? Because comments are not code. They are not an integral part of the running program. They are not bound by syntax or verified by unit testing.
This wouldn‘t be so bad if that code were never subsequently to be changed. Code is always changing. As agilists we‘re always tweaking and refactoring our code to reflect new or changing requirements. It‘s all part of embracing change. There is therefore nothing (beyond attentive human inspection) to prevent comments from becoming stale, detached or irrelevant. Stale, detached or irrelevant comments are worse than no comments. Opaque code with no comments merely obfuscates, opaque code with stale comments lies.
So what‘s the alternative? It is is more–or–less accepted wisdom now that if it is unclear what some code does (or at least what is intended) by reading it then it should be refactored so that it is clear, elegant and expressive. Rename methods, extract unclear code into new methods and classes, reduce responsibilities.
This is all expressed more elegantly and in far more detail by Bob Martin in Clean Code and countless other books and articles that predate it.
What about the ‘why‘
Jeff Atwood has already contributed his tuppence worth on this subject and I agree with a lot of he says. Apart one from one thing, he says that comments have a legitimate role in describing to the reader the reasoning behind decisions to implement a solution in a given way. I agree with him that it is difficult to express this information in code alone and that an additional enrichment of the code is required. I think he‘s wrong to say that comments are the best way to achieve this.
Version history and meaningful commit messages can better and more reliably express the reasons behind decisions made. I do this all the time in my day to day coding. If I see some code that I fail to understand the reasoning behind I look up the history of the file and read the commit messages. The code base I‘m currently working with has undergone a lot of change and few of the many comments that litter the code are of any use. Luckily, there is a wealth of information in the Subversion commits, some with references to issues in JIRA.
The commit messages are persistent and reliably associated with lines of code. They don‘t become stale and they don‘t become detached from their context.
Ugly
So there it is. Code comments are bad, they‘re ugly and they create more trouble than their worth.
More than anything, it‘s the ugliness I take most issue with.
If you‘re into software craftsmanship, then you‘re interested in elegant and (dare I say it) beautiful code. You‘re interested in code that tells a story, that expresses to the reader your intention. Essentially, this is code that documents itself. This sort of code does not need comments.
First published on May 19, 2010. Last updated on: May 19, 2010.
I'm Elwyn Malethan and this is my blog. I am an aspiring 