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 a software craftsman with over 10
years of commercial experience. When I'm not doing my day job at
Agreed!
This is the most inane and plain incorrect posting I‘ve ever read.
I pity the developer that inherits code you‘ve written.
Everyone strives for clean code, but even clean code can‘t always express why something is the way it is.
Every file, every member variable and every method needs a comment. Without it, no matter how clean the code, you‘re taking someone into a maze in the dark and blowing out their light.
Obvious troll is obvious.
I‘d have to disagree. There are too many times where I‘d have to go back and modify code I‘ve written 1–3 years ago, and when you have pages and pages of code it takes a lot longer to make the changes you need if you don‘t put comments in. Overcommenting is annoying and unnecessary, but if you have complex functions or a ton of code in a single script, you should comment parts that may be confusing to people, including yourself.
What‘s your take on java docs on webservice interfaces and such, that will be used by other teams.
I mostly agree with you. But I‘m not sure I‘m on board with the whole “look it up in the commit logs“ approach to things.
First, most people who are reading the code want an explanation of “this bit right here, right now“. To force them to go through (potentially) hundreds of commit messages to find the one message that describes the reason for the change is downright sadistic.
Second, I cannot count the number of times someone on my team has committed with a message like “minor tweaks“ or “refactor“ or “changed code”. Unless you (as the team lead) are monitoring each and every commit in near-real-time, you will sooner-or-later wind up with an inadequate commit message. And this brings me to point #3…
Third, unless you have sufficient privileges in you SCM system, you cannot easily change a commit message. If you get a bad commit message, you are stuck with it. Forever. At least a code comment can be changed.
And finally, when you change SCM‘s there is a very real possibility that you will lose your commit history. What then?
@John
I‘m pretty happy with the code I write for the most part, so are the people I‘ve worked with.
What I express in this post is an ideal. Essentially what I‘m saying is if code looks like it needs commenting, then look for another solution before resorting to comments.
@David (if it really is you)
I‘m honoured you‘ve graced my website with your presence. Whilst I am interested in people‘s views/responses (though hopefully not overtly emotional) on this subject, I don‘t think this post qualifies as a troll. It is neither off-topic nor disruptive. In fact, I think it is entirely legitimate and constructive to express views on a subject that affects most developers.
@Vanessa
What you describe there is what sounds like very un-clean code. I concede that if you don‘t refactor it, comments may be your only refuge. All I‘m saying is that it is far from an ideal solution.
@Rajesh
Public APIs are a totally different situation in my opinion. Whilst those public APIs should be well designed and clean themselves, documentation of those APIs should be as close to the code as possible (i.e. in-line such as in the case of JavaDocs). That documentation should be clear and plentiful.
@Jeff
You‘re concerns are valid. Being able to use SCM for this purpose requires good tooling and above all discipline and attention to detail. It requires these qualities amongst the entire team. I agree with you that there are potential weaknesses in this approach.
Your whole premise relies on the the whole team writing “clean“code. Sorry to say i‘ve never been on a team like that in 15 years of programming at companies of various sizes. Inline comments are the easiest way to give the intent of something if its necessary. I have worked with maybe two people who put in decent commit comments and even then having to dig thru them is ridiculous. I‘d rather have less then ideal comments in code vs having to dig through commit messages because they‘re where they‘re supposed to be…close to the code. I find it very odd you‘d want to look elsewhere for code intent than the code itself.
Though I work with a guy who considers himself a software “craftsman” who thinks code review/inspection is meaningless so maybe I shouldn‘t find it so odd.
@Jason
Thanks for your comment.
I have no argument with you that inline comments are the easiest way to explain bad code. It‘s just not the best. Producing clean code is better.
The key of good programming is the clean, easy readable code supported with comments. The comments prepare the reader for the logic of code and give him fastest way to understand it, the case without comments can be for personal cases when the reader is the creator of the code … wtf!
The whole point here is about time.
If you have little time you don‘t write enough comment in the first place, and after when you are correcting a bug, add a functionnality or refactor, you don‘t update the comments with the code.
Maintening a good code comment is just a step futher in quality. Many time you can‘t aford it and you have to live with bad, obsolete comments.
But when you hand up with a good quality code, it‘s pleasure. The point is top quality code with comments and all, surely cost 2x, 3x the time to implements at first and it‘s very difficult to justify that.
Even if in the long run, sometime, making top quality code is better.
@John: Really? What comment would be useful for this:
private String firstName;Please don‘t say anything resembling “User‘s first name.”
What comment would be useful for this:
public String getFirstName()...Please don‘t say anything resembling “Returns user‘s first name.”
@Vanessa: As long as the comments explain why something was done, fine. I can even almost deal with “Fixes Defect#xxxx: Re-login doesn‘t get new session” or whatever. But I‘m with Clean Code on this: comments rarely stay in sync, and rarely provide more information than properly named and refactored code.