Making Good Software

A blog by Alberto G (Alberto Gutierrez)

Written by Alberto G

June 6th, 2009 at 12:23 pm

Comments are evil?

with 8 comments

I have recently published an article called “10 commandments for creating good code“, in which the commandment number 8 says “Comments are evil”, well, as I was expecting this has created some controversy and a few comments have been written in dzone.com and news.ycombinator.com arguing about comments being evil, so I have decided to write this small post where I hope I can bring some light into what I really mean when I say “Comments are evil”.

Code quality scale

I believe most of the developers will agree with the following scale.

  • The worst code is: Bad code without comments.

  • Bad code is: Bad code with comments.

  • The average code is: Average code with comments.

  • Good code is: Good code with a few comments…

  • …but… Great code doesn’t need comments!!!

DRY

First commandment in the “10 commandments for creating good code” is DRY (Don’t repeat yourself), I believe this is the main guideline for a software developer, what most software developers don’t see is that every time a comment is written, you are repeating yourself! Now not only you will have to perform maintenance activities on the code, but you will also need to make sure that the comment keeps its synchronicity with the code. Not a big deal? Well, think in all the other principles you follow when you code, each of the small changes you perform in your code to make it better, like spending time to name a class, moving a method to a different class because it just feels right… are insignificant by themselves, is when you put all them together when you can tell that you have created a masterpiece of code.

Should we use comments at all?

Of course!!!!!!! My mistake was to name the commandment “Comments are evil”, is just a guideline, as any other principle you apply in software development, sometimes we just produce crappy code, for many reasons, we are under pressure, we don’t know the technology we are working with… Then for the love of god, use comments!! There are other times where we have prodcuded good code wich has a few comments, that’s fine, we cannot always look for the perfection. What “comments are evil” really means is that you should always push yourself to use as few comments as possible, not because you are lazy, but because they are not necessary.

8 Responses to 'Comments are evil?'

Subscribe to comments with RSS or TrackBack to 'Comments are evil?'.

  1. [...] 9 comments « Refactoring: The 5 main questions: Why? When? What? How? Who? Comments are evil? [...]

  2. Comments are only a repetition if what you put in them is the “what”. The “what” is, indeed, already there in the form of the code. However, the “why” is often pretty much impossible to put directly into the code itself.

    Say you’re faced with some credit card processing code that sends all credit card numbers through validation for the CVV2 (that little number on the signature panel), but there’s this extra bit that sends American Express cards around that particular validation.

    The kind of code comment you are talking about being repetitive would say something like:

    //Bypassing CVV2 validation for American Express cards.

    That comment clearly is redundant because code like this already makes that pretty clear:

    if(creditCard.CardType == CardTypes.AmericanExpress)
    {

    } else
    {
    isValidCVV2 = creditCard.ValidateCVV2();
    }

    However, when you’re looking at that code, the question you have in your mind is this:

    Q: Why is the code not checking the CVV2 number for American Express cards but *is* checking for the rest?

    A: Because American Express wants to come on site and do audits if you check that and the product owner would rather pay the higher rate to process the cards than deal with the audit

    That answer is what good comments should contain. That can mean that there are large blocks of code without comments (because the “why” is not necessary), but whenever there ARE comments, they should be explaining the “why”, not the “what”. Then, they aren’t repeating yourself.

    “What” comments aren’t necessary. “Why” comments are the lifeblood of a maintainable codebase. They let you go to the people who oversee the credit card processing agreement and see if that “why” still holds true when you’re asked to dig into the credit card validation for other reasons and see if it should be left the way it is.

    J Wynia

    6 Jun 09 at 3:27 pm

  3. I’m afraid I must agree with Wynia. Just the other day I encountered a loop which started iterating over an array from 1 instead of 0 and as a result choked when interacting with client code. I changed it to start from 0 and things seemed to work from 0. The code itself was simple to understand, but I have no way to tell why it was starting from 1 or if I might have broken something else in the process. If the developer was in the habit of always commenting whys he would have paused to think about the start of 1 and written a comment about why it was there. And if it was a mistake, he would have looked over his code to see if it needed explaining and perhaps caught the mistake.
    I think we should strive for the right number of comments as opposed to the fewest. It’s better to go a bit overboard than a bit under.

    Basu

    6 Jun 09 at 3:52 pm

  4. People seem to forget that there’s nothing like wrong comments to set you off on a wild goose chase. If the code has no comments, the comments at least cannot be wrong.

    Svend Tofte

    8 Jul 09 at 12:48 pm

  5. The biggest overhead of repeating “code” is when you have to repeat the effort of maintaining the code and the repeat of the code, in this case comments.

    Having code with less repeats -the same principle behind generic usable code- avoids this overhead and avoids having situations where the duplication goes out of synch.

    Imagine how confusing comments that are out synch with the actual code can be.

    Tseliso

    6 Aug 09 at 11:34 pm

  6. [...] heard a lot of times that comments are considered as an evil. And yet we always found a way to say, ‘but in [...]

  7. Hi Alberto,

    thanks for the interesting articles in your blog. For this article, however, I have to disagree. I think most of us all know this viewpoint from some kind of Agile-Book, but I think it’s just so plain wrong. Wynia has already said some wise words about comments. Sometimes they just can’t be let out to make the “why” clear.

    There’s some other aspect I want to make clear about commenting code: At least interfaces should ALWAYS be documented thoroughly to make their contract and intention clear. It’s exactly that thing – the missing contract – that sometimes gives me a hard time, when faced with a method, used a dozen of times in the code but not working like expected. Now in that case it would have really helped to know HOW the method was expected to behave…

    Another point about comments is, like Basu stated already, that they make you think about your code. Don’t underestimate that fact!

    About the “out of sync”-problem: Sorry, but I think that’s really a problem that doesn’t lie in the comments but in the laziness of the developer…

    As a last thing: Imagine the J2SE or J2EE libraries without their thorough documentation: Now is that crappy code? I wonder what the people of the “Comments indicate bad code”-fraction will do if they once more stumble upon a really sparse documented Open-Source-Library. In my mind I can already hear them rejoyce because they once more found a piece of software that’s so great that it doesn’t need any comments. Get my point? :)

    Greate article about that subject from Brian Goetz: http://www.ibm.com/developerworks/java/library/j-jtp0821.html

    Achim

    23 Jun 10 at 11:17 pm

  8. Hi Achim!

    Thanks for your comment, you indeed highlight a lot of points that make a lot of sense… Actually, I have to admit that reading again the article it does sound too extremistic, I really think you are right, there is times when a comment is necessary…

    Thanks for your great feedback!!!

    Alberto Gutierrez

    24 Jun 10 at 12:27 pm

Leave a Reply