The title of this post comes from Robert C. Martin’s Clean Code, which embarrassingly enough I have yet to read. I stumbled across this as I was formulating my thoughts for this post, which had been percolating for a while. I was looking for a snappy title which summed up what I believed, and “comments are always failures” does it perfectly.
There is really not much to say here. I’ve challenged the notion myself, as I’m not a believer in generalizations. But in every case I can recall in my team’s recent work, a comment was indicative of simply not having enough time to do things right. For example:
- “Since we don’t have that database in our development environment, just comment that test out so we can have it for reference when we do need to run that test.”
- “Those data-dependent tests are failing because some data changed (go figure), just comment them out until we have enough time to go back and fix them.
- “So the business wants us to do something with this object that is counter to what the object name means? Go ahead, implement the change, and then add a comment so we remember what we did 3 months from now.”
- “Oh look, a comment that says ‘need to do this better.’”
And then there are the myriad other comments that add no worth, e.g. a comment that says “Applies taxes to purchase amount” on a method called “ApplyTaxesToPurchaseAmount.” In every case, had we had the time, we would have been better off removing the comments and making our code more intentful. Comments are a crutch that allow us, in our lazy moments, to accept less-then-perfect object names, method names, and class hierarchies, all because we have a comment nearby that really explains what we meant. Garbage.
Comments are always failures. As developers, we need to drill this into our heads and make it a mantra. We need to augment our automated builds such that instead of warning us if we don’t have at least X% comments, it fails the build if we have above X% of our code as comments. Instead of having to subtly switch gears in my head during a code review when I come across your comments so I can read and understand your prose, I should immediately ask “what happened here that we had to add a comment?”
Comments are always failures. I challenge anyone to prove this wrong.
[...] my thoughts for this post, which had been percolating for a while. I was looking for a snappy… [full post] barebonescoder Musings of the Bare Bones Coder codingsoftware craftsmanship 0 [...]
One very useful scenario with comments that I don’t see mentioned above:
// Bug : Internet Explorer/Weird Database/whatever fails if we don’t make sure we do X before Y
It’s very hard to make that sort of intent obvious in the code – especially where an ordering constraint is non-obvious.
I think it is very easy to abuse comments, but unless the software has changed completely beyond all reckoning, or the comments are far too global in scope, I think they can be very useful.
Defects shouldn’t be catalogued in code. They belong first in whatever bug tracking system you have for your product. Is it worth having records of defects in two different places? I don’t think so anymore.
I have to disagree. i work on a big codebase (more than ten millions line of code for our departement only), with a huge bug tracking system (we have more than 400 000 bug logged into it).
When you do a modification on the code, or correct another bug, you have to insert your own modification into the code. You will not use your SCM to check all of the history of each file, and read all SCM comments, and reconstruct the graph from the hundred branches used. You’ll not search the whole bug database in the hope to found the bugs potentialy related to this code.
What you do is that you read the code. You have a here or a strange behaviour. And the guy that introduced this behaviour has been queen enough to :
- explain the real intent of this code
- put in the bug number or reference to the specification document into a comment. (this last one is mandatory in our team).
Then you understand why this code is here, why there is this “strange” behaviour. Then you know what should be preserved in this strange behaviour, what can be changed. You can call the guy that made the modification, you can go read the specification, ask the relevant team…
When you work on a departement of more than 800 persons, where some are newbies (yes you have to live with that…) where theres ares hundred of modifications done per days, you really care about comments.
[...] This post was mentioned on Twitter by Proggit Articles, Jeff Vera. Jeff Vera said: Blogged: Comments Are Always Failures http://www.barebonescoder.com/2011/01/comments-are-always-failures/ [...]
You clearly have much more professional coding experience than I do, but I do think that comments can be useful to people who are *learning* how to code.
Clean, well-written code will probably help a novice more.
As someone who remembers what is like to be a novice, I have to disagree. That statement is 100% wrong. Whenever I skim across a huge piece of code without comments, I get totally lost. It’s impossible to see the intent of a block of code without really focusing and following it through in your head. With comments I can skim it in a couple of seconds.
And for newbies who don’t fully comprehend what everything does, it’s a godsend. And comments like “Add two and two together” don’t help anyone, but nobody has ever said that those comments are a good idea. And by the looks of your list you chose only to take those scenarios as examples.
Your point actually supports my statement.
“Whenever I skim across a huge piece of code without comments, I get totally lost.”
That is a failure of the collective authors of that code base to write said code in self-describing way. While comments might help you understand said code, had it been written better in the first place, then you wouldn’t NEED the comments.
Next time you find yourself writing comments, ask yourself why, truly why. Push past the commonly-held notion of “that’s what we’ve always done.” You’ll be surprised what you find.
You’re doing it wrong.
Comments should indicate intent, assumptions, and warnings.
If you’re commenting out code in order to “come back to it later”, you’re not using your version control system properly (and if you’re not using version control, you’re an idiot). The examples given don’t reflect that usage, and as such, they’re basically noise. Their sole advantage is that they’re in the code, where they’re available for all to see, rather than in an email archive, out of sight and out of mind.
So, if that’s the only sort of comments you see and/or write, sure, comments are failures.
But, if you’re writing decent comments… the comments describe *what* you want to happen, and the code is *how* you make it happen.
When the code and comments are in conflict, then, the error is in the code, and by definition, a bug.
Why is the error in the code? Well, it’s simply not possible to look at a piece of code and then to discern the intent. Perhaps you *meant* to send SIGSEGV to the parent process, or to overflow the integer value. There’s no way to tell just by looking at the code.
Programmers can quite legitimately desire conflicting behavior… so I can “fix” some code so it behaves one way, and you can “fix” it back, and we’ll be caught up in an endless loop of bugfixes that aren’t. Coupled with the prevalence of actual bugs, only the most obvious bugs are detectable from code inspection.
The code is what the code is.
Comments are what you *mean*.
The *what* of your code should NOT be in the code. It should be somewhere that’s accessible to all business shareholders. Or is DRY only applicable to code and not the business requirements that code is trying to meet?
It most definitely SHOULD be possible to look at a piece of code and discern the intent. The problem is that most developers have been conditioned that it is OK to not be able to do this, mainly due to the large legacy codebases that we have been saddled with throughout the corporate world.
We as developers need to stop settling and accepting and start aspiring. The comments you describe belong in a place where *everyone* can get at them; that is shared business knowledge that belongs to not just the coders, but also the other business shareholders you work with.
Comments are failures, and that’s OK. We can be better.
Imagine that i coded a complex algorithm, i use good method names, but i have put no comment, said nothing about the details, the optimisation have done, the restrictions specifics to my needs. Then there is a bug (maybe) in the code, and you have to correct it… The trick is that you don’t even know what it should do.
I wish you good luck.
Your coding of a complex algorithm and some “optimization” that isn’t evident from the name of the classes and methods is a failure.
Someone other than you should be able to easily intuit the meaning of your code (and the thrust of implementation) without having to resort to comments.
You view is naive.
First an interesting code is more than the simple sum of it’s parts. Saying that you can understand code just by reading it (and without comment) is like saying you can understand our DNA by just reading the sequence of ACGT letters in it.
There is uninterresting boiler plate code and there is code that do really something interresting. Complex algorythm implementation may need only a few lines (or few hundred lines) and expressed in a good way. But without comments it would be unmaintenable and understandable.
Also there is another reallity that make you view unpraticable : you never design and implement the whole system. Even if you would be the GUY, the perfect programmer that would be able to make any code what ever complex understandable by anybody the first time they read it, well … you still have to deal with the fact that most of your software is not coded by you but by others.
Yes your program depends of instruction code of the processor you use, it depends of OS, maybe a virtual machine, the compiler, a base API, a bunch of frameworks, the old code of your software, the other systems with wich you communicate…
All of theses have limitations, problems workarounds, bugs, design changes.
And you have to deal with that. In fact the daily work of a programmer is not to do something by himself, but to manage the dozen of frameworks, libraries, external service the software and use, with their limitations and all… And write code that do the correct workaround so the sofware do what is intended despite the limitations or unintuitive behaviour of the surrounding environment.
Code that do not need comment is worth nothing anyway. It doesn’t deal with reallity, it just some theoretical program that would fail in production and implements simplistics boilerplate code that is there only because the underlying programming language is verbose (like java).
And how do you feel about javadoc for Java API ?
How about removing all comments ? So there is no javadoc. After all
Good comments describe the intention of a piece of code on a higher level than what can be expressed by the code it self. It explains why it was coded that way. This is especially important for highly sophisticated and nontrivial algorithms, where the way it works may not be easy to grasp. The comments can then refer to papers and/or documentation that describe the algorithm. Other cases is domain knowledge for the domain of the particular software. I cannot see how putting comments like that into code is a failure, as it does not describe any failures or workarounds, but rather makes it easier for the next guy to understand the code, and not screw up because he changed some part of the code he did not understand.
If you name the entry point into your algorithm after the name of said algorithm, and then decompose the underlying code into small, testable chunks, then there is no need for comments. If I want the backing theory of the algorithm I will search it out, ideally in a shared repository where our business stores its rules, or worse, on the Internet.
The point is, it does not belong in the code.
First off, I applaud your premise and I would prefer that you are right. (I also
like your default position against generalizations. I dislike the overuse of
generalizations as well, but I’m about to make several.) But there’s a
fundamental problem I have trouble getting around. Human language
(English in this case) is what we use to communicate with humans, machine
language (e.g. C#) is what we use to communicate with machines. Even the
most seasoned of developers still has to read a programming book to learn
new technologies, instead of just looking at code examples – speaking for
myself at least. Even if you know the technology well, when you look at code
someone else wrote, it’s new to you and you have to “learn” thier code.
We’re comparing comments vs well written code – let’s put the best of each
against each other in a hypothetical example. Imagine what you would
consider to be a well written function that performs some complex logic that
is specific to an application. That function has a well written comment above
the function header. Reading which would give you the quickest high level
understanding of what this function does? For me, I’d probably go through
the code first, realize it’s complicated and look to the comment for context,
intent, etc, and then go back to the code, ideally better prepared to
understand this complex logic. I love the concept of aspiring to make code so
well written that comments are unnecessary and perhaps it’s possible. But
communicating in our first language would seem to be the more effective and
natural choice.
I’m glad you acknowledge that writing such code is requires additional time.
This is something high level decision makers in corporations I have worked
for often don’t understand or is something they do not value even when they
do understand. It’s usually more about getting the latest and greatest
features in before the competition so our salesmen can sell them. This is a
situation where comments become necessary, because developers aren’t
provided the time to write the code as self documenting as it could be. As far
as the documentation being handled outside the app, design documents have
been at best a formality that are not maintained if they are ever created at all.
Even if you did have great documentation outside the app, you then have to
look away from the code to another source as opposed to having embedded
documentation in the form of comments.
The problem with documentation in the code is that only serves one business group – the coders. We as developers have accepted this state of affairs because it’s easy and it suits us. Every reason in this comment thread for comments NOT being failures resonates with my past experience. But it also supports the laziness that I used to accept: “that’s just the way it’s been.”
If there is a method that performs a complex function that makes your eyes glaze over and make you look up above for some friendly green text, then that’s your first indication that said method is a candidate for refactoring. Instead of saying code comments are good enough, let’s demand something better: clean code as self-documenting as possible, coupled with domain knowledge explained in repositories of knowledge that are equally accessible by both developer and CEO alike.
I agree with Patrick that there are some (rare) exceptions, where comments are useful, but also agree that his example is flawed. If you need to find out what a specific complex method does, that information should be contained in the method’s name. If the method does so many things, that you can’t list them all in the name, then you can either refactor it, or admit failure and comment it.
Clean Code explains all of this in a very beautiful way. I highly recommend it, it’s really an eye opening experience about many things.
“Programs must be written for people to read, and only incidentally for machines to execute.”
Abelson & Sussman, SICP, preface to the first edition
Outside of trivial examples, the idealism you describe of the code documenting itself does not exist.
The code I’m helping to write now is certainly not trivial, and aspires to what I wrote about re: comments as failures.
And frankly, the quote you cite supports either side of the argument based on interpretation.
We need to learn to write better code.
While I don’t disagree with the premise, the message is poorly executed. “Comments are always failures” requires explanation. It requires commentary on why and what. It’s also fairly aggressive and negative. Imagine being told that, flat out, that something you did was a failure.
Instead, if we wanted to get fancy and concise, with a positive outlook and more conducive to getting across the idea, we can use “Comments indicate future refactoring.” Whereas “comments are always failures” is negative, and doesn’t indicate a goal, “Comments indicate future factoring” is a clear call to action. It tells us what to look for and what to do.
I believe that the statement “comments are always failures” is aggressive only to those who don’t recognize that failure is a necessary component of success.
It’s OK to fail, provided you learn and strive in earnest to improve next time around.
I’ve found that it’s much more beneficial and useful to be clear, concise, and not beat around the bush when providing feedback. The notion that “comments are always failures” is a simple statement of fact, and does in fact indicate a goal; it is the goal that is implicit in any failure: do your best to not fail again.
> I believe that the statement “comments are always failures” is aggressive only to those who don’t recognize that failure is a necessary component of success.
Except practically every comment on this post seems to disagree, or not understand. The message is muddled. And while you might believe the message is aggressive only to those who don’t recognise that a failure is a part of success, I disagree. I fully realise failure is a part of success and I still find it aggressive.
Communication is a two way street. If you want to push an idea, you have to make that idea accessible.
Indeed, one could take your statement and simply infer that your commentary is, in fact, indicative of failure.
> The notion that “comments are always failures” is a simple statement of fact, and does in fact indicate a goal; it is the goal that is implicit in any failure: do your best to not fail again.
That’s really digging for something. The statement itself is not a goal. You have to infer too much, and the statement itself can be muddled. More to the point, even your inferred goal is poor at best as the simplest solution to accomplish the goal is to not write comments.
Heck, I’d go so far to say that removing comments from code is worse than having comments in them merely to achieve the goal of not having commented code. You yourself admit freely to using comments for good in your original article.
If anything, “Comments are always failures” is incomplete. “Comments are always failure, but not always bad.”
> Instead of having to subtly switch gears in my head during a code review when I come across your comments so I can read and understand your prose, I should immediately ask “what happened here that we had to add a comment?”
Here is a perfect case where a comment is helping you to address a deficiency. If all comments are removed, you’d have, as you point out, no easily identifiable point to review failure in code. By leaving the comments in until the problem is solved, you essentially provide easy to reach targets.
Oh, you might argue that this only applies to legacy code. But I challenge you to blindly remove comments from everything without using the comments to review the code they sit beside.