Stop commenting your code just to say you did

Summary – Code comments that point out the obvious make the important comments harder to spot. Developers are better off when there are only a few comments for the code that deserves an explanation.

5799338412_70bd536ff1_bYou open up an electrical box and see a few hundred wires. Lots of different colours that don’t mean a heck of a lot. But someone has put a neat little label on every wire. Awesome!

Or so it seemed until you actually start looking at the labels. Almost all of them are blank!

So you spend an hour digging through every label. In the end, you find a total of 12 actually written with an important message. Hopefully you didn’t miss any in all the chaos.

This is how I feel when I dig into code with useless comments everywhere. It’s hard to identify useful comments in the sea of useless ones. Needles in a stack of needles.

Here’s a great example that shows up everywhere in a very popular open source project:

 * __construct function.
 * @access public
 * @return void
public function __construct() {

And another one…

 * Constructor
 public function __construct() {

And here’s another gem…

// Convert float to string
$value = float_to_string( $value );

These comments are similar to the blank labels in the electrical box. They point out the obvious, add noise, and diminish the overall usefulness of commenting. After reading a few of these comments, I wouldn’t blame any developer for ignoring the rest.

6839927041_419efba7b6_bI’m sure the electrician that took the time to put blank labels on each wire thought he was doing a great service to those who would come after him. After all, the label is already there, they just have to write the note now. Or maybe he had intended to fill in all the labels, but never got around to it. Regardless of his good intentions, the result is a much worse situation than if he had only labelled the 12 wires.

In the coding world, developers are told they should always comment their code, but rarely are they told how to do so. And so comments are often written because developers feel an obligation to do so, not because a comment is needed. They feel they are doing their job well if they add lots of comments, regardless of their quality.

I can’t accept this. I would much rather see a few comments explaining why some code is needed than a comment on every few lines that say nothing. Comments shouldn’t be written purely to show we’re “good little programmers.” We should use comments sparingly and mainly to “document the why”.

// We need to account for product price changes,
// so we get the price of the product when each order occurred
$order_prices = $this->get_order_prices();

When deciding if I should write a comment or not, I ask myself a simple question: if I come back to this bit of code, will it be obvious why it’s been written this particular way? If my future self will be very thankful for an explanation, then it’s a no brainer, I write the comment. Otherwise, I let the code speak for itself.

Further Reading

  • Some of those comments aren’t there to describe how the code works or why it does what it does, they are there to provide metadata for the code itself so that automated processes can read your code – things like documenation generators like dOxygen, and IDE’s.

    I agree that there are plenty of noisy comments out there, but your first example isn’t one of them.

  • lmm

    I think if a documentation tool requires adding a lot of noise to your code then it’s a bad tool.

  • Overly commented code is the sign of a rookie

  • Brannock Device

    Maybe, but rookies probably shouldn’t skip that stage too quickly. They need to learn how to write good comments. And some of that learning comes from figuring out what bad comments are.

    If the rookie reads this article and says to themselves: “I don’t need to comment”. Then maybe they won’t learn to write the good comments.

  • Deniz Özger

    We usually add comments when the code just bad (ie. not readable) so almost always comments are signs of bad code. Each time you feel like adding a comment, ask yourself “How can I express myself better in the code so that the readers won’t need to read comments to understand the code”. Re-write the code instead of commenting.

  • Ken

    But surely the documentation generators can detect that the function is named __construct, returns void and is public? It’s all right there in the definition.

    I would contend that any documentation generator should be able to document the basic signature of your functions, and you should only comment the things that aren’t trivial.

  • Graham – pretty much the main standard in Java API documentation, and used by Eclipse / InteliJ / other IDEs for autocomplete. – To generate docs for things like Javascript as you described is close to impossible – so this is required.

  • Comments are not there to help the reader understand the code. Comments are there to help the reader understand the problem the code is attempting to solve.

  • Even a super tool may need a super language.

  • Very nice topic. If you haven’t already read it, you should pick up Clean Code, by Robert Martin. Pretty much states what you said in more detail.

    Commenting is just a failure to make your code readable, so in most cases we should try to rewrite rather than just comment. When that fails, then and only then we can comment.

  • Mike McMahon

    if a rookie reads this article and decides “i don’t need to comment.” Then they have taken the absolutely wrong message away from this article.

  • Totally agree with you. I can’t stand comments which tell me the obvious, especially when they are there just for documentation generators. Surely they should be able to infer all the relevant information from the function prototypes?

  • Mchl

    But it is (close to) impossible, because language syntax does not tell the generator anything about argument or return types, so it won’t tell these things to human reading the code either. In such cases documentation comment is not redundant.

  • Xela Etihw

    You have to maintain comments (bad unless they are good comments that add value) or let them diverge from the code (worse).

    Bad comments sap your precious resource – time, and it propagates would you remove a (bad?) comment you don’t understand?

    Comment wisely 🙂

  • Arve Systad

    To be fair, in the first example – all the metadata that is added is also part of the code itself. Why require these silly comments to repeat it all when the IDE can just read it from the code itself? Yes, the IDE might not be able to do so, but the comment is still – no matter how you look at it – just duplicating the information that the code already gives.

    So unsophisticated IDE + silly standards for commenting == Twice the ugly.

    Edit: …basically what @lmm said. I was too lazy to read that first.

  • Because the IDE cannot read it from the code itself. Neither can any tool out there sophisticated or otherwise. There is no way to determine that a function returns void in php. So you have a standard way of communicating that information, it means that you don’t have to dig around in the codebase to see if the method being called on some object is going to give you some response.

    IDE’s also have a handy setting that lets you shut off docbloc comments when you are wading through code so that you dont have to look at anything except the actual comment part, so ugly isnt even an issue.

  • Arve Systad

    Allright, return type is fine. But the code explicitly gives us the name of the function and it’s access modifier, so that could (should be) easily be removed.

  • Peter Jensen

    I am a rookie, and i really found this article informing. Commenting is not being covered very much, we are just being told that we should always remember to comment in our code.


    I will add this to my blog as well. Thank you for the information.

  • Thank you for share this information.

  • Ron Donaldson

    Worse than being blank, the labels in your electrical box would probably include stupid things like “green wire” and “connect port 135 to port 67”

  • Hello Brad Touesnard,Thanks For Sharing Information About open source describe how the code works. Electricians Toronto