Should I Comment My Code? The Case Against Code Comments


A question asked by aspiring and experienced developers alike is: should I comment my code? This discussion typically stirs up a lively debate with developers. However I don’t think the question has a right or wrong answer. Instead I think the answer is: it depends.

In this guide I want to take a practical look at when code comments can be beneficial along with when comments cause issues.

Should I Comment My Code?

When code comments go bad

I remember back when I learned how to code. A common theme I heard was that all of my code should be commented. This seemed like a good idea at first. And in a perfect world comments would be beneficial. However we do not live in a perfect world.

Let’s jump into a time machine and look back at how I might have commented a method years ago.

should I comment my code

If you run this code you’ll see that it all works properly.

should I comment my code

So what’s the problem?

Since the one constant rule of software development is that requirements change, let’s imagine that our program needs to be updated to also print out the player’s position.

should I comment my code

In this code I’ve updated the method so that it takes in a key/value hash and prints out the player, lineup number, and position. This works properly when I pass in a hash argument.

should I comment my code

But did you notice something? I didn’t update my comments and the instructions still are calling for an array. If I need to work with the method in the future and I reference my comments and pass in an array, the program no longer works properly.

should I comment my code

So what’s the main problem with code comments? The issue comes down to the fact that they are fragile and can’t be trusted. Comments, by their nature, are static. This means that you could completely change the behavior of a method, and if you don’t update the comments they will be rendered useless.

When I take on a legacy application and look at the comments it’s rare that they’re still applicable to the current system.

Code that Explains Itself

Through the years I’ve slowly stopped commenting my behavior based code, such as classes or methods. Instead I’ve focused on improving the names that I give parts of my programs. I’ve discovered that if I name a code component properly, comments are no longer needed.

David Heinemeier Hansson, the creator of the Rails framework, had this to say about the importance of naming:

“One of the real delights of programming is picking great variable, method, and class names. But an even greater treat is when you can name pairs, or even whole narratives, that fit just right.”

In this guide he gives a great narrative on a specific time he was intentional in regard to naming a method.

When Code Comments are Beneficial

With all of the bashing that I’ve done in regard to code comments, you may be wondering: is there ever a time when commenting is beneficial? The answer is: yes.

I don’t like add comments to code in order to explain functionality, because behavior constantly changes. However I have found two ways to incorporate comments that have proven to be helpful.

Code Organization

First and foremost, I will utilize code comments for code organization. I have discovered that comments can be helpful for large code files such as CSS style files. I’ll add comments such as: /* Nav header styles */. These types of comments let me quickly know where a specific set of styles can be found. And because these types of comments don’t give instructions or describe behavior, they’re far less likely to get outdated.

Automated Comments

Next I’ve discovered that automated comments can be helpful for reference purposes. For example, the Annotate Ruby gem will automatically create and update comments in code files that supply database information. When I work on a Rails application I’m constantly referencing the database schema file to ensure I’m selecting the correct column names. The Annotate gem automates this process by commenting model files with the table information.

When it comes to working with code comments, automated tools that will also update the comments can be beneficial to a developer’s workflow.

Should I Comment My Code Summary

In summary, code comments can lead to a number of negative issues for programs. Comments are fragile, can be misleading, and perform a poor job of explaining application behavior. A better choice is to improve at method naming, so that your code explains itself.

After publishing this guide, developer Kiss György pointed out a great quote from Robert ‘Uncle Bob’ Martin who said:

“Every comment you write is a failure to express yourself well in code.”


    • Like I mentioned, in a perfect world that would be how it would be done. However after going through dozens of legacy applications it’s incredibly rare that I’ll find comments that relate to the most updated version of the code. When I ask the previous developer about it the answer is always: “oh yeah, I need to update those, I just got busy when working on new features and meant to go back”. That seems to be the core problem is that nothing forces developers to update the comments because they don’t apply to actual functionality.

        • If you read the article I don’t suggest to never use comments. I list a few spots where comments make sense and won’t cause issues. I’m more referencing developers who add comments as either a crutch for writing poorly named/organized code, or writing comments and then forgetting to update them later on (something I’ve seen countless devs do).

  1. weak argument in my mind. Comments are an important declaration of intent that should be included on public API as a minimum. They dont disobey the principles of DRY because they are comments, not code. The easy way to ensure they are kept upto date (if you really cant remember) is to make sure they are part of coding guidelines that are enforced when code is reviewed. Either as part of contribution or as validation of a pull or merge request. Diffs available on most source tools are easily good enough to highlight API changes that would necessitate comment changes and to identify changed logic that might indicate to a reviewer that the contract had semantic changes. DONE.

    • I just added a quote to the article from Robert “Uncle Bob” Martin that put it best: “Every comment you write is a failure to express yourself well in code.” That’s unrelated to your point, but still important for the discussion.

      And comments do break the DRY principle. They’re comments, but if you need to make multiple changes for a single code change (whether you’re changing comments or code) that’s the very definition of repeating yourself.

      • I couldn’t agree more with Uncle Bob’s quote. In general if I feel the temptation to add comments on my code I take a step back and check if I can do a refactor instead. However there are some type of comments that can’t be avoided like legal comments. So I’d go with the author conclusion. Do we need comments? Well, it depends, but in general comments are:
        – hard to mantain
        – get obsolete fast
        – could be an excuse to not improve the code
        – potentially can break the code block cohesion

      • Im not sure how a quote from Uncle Bob Martin is relevant. He’s very good at academic arguments but his opinion about never commenting code has been shot down multiple times, and rightly so. I’m not a fan of commenting every twist and turn but I insist on public API documentation for many reasons. Context is one major one, the why, if i begin trying to express why i am doing something in code as well as doing it then I’m adding semantics to the imperative which is plain daft. Also (and just as important) IDEs for many of the tools me and my team use are able to surface function and header comments everywhere. Why should they go and read the code when a descriptive comment tells them from where they are. There is also clarity. If i have a method, as part of my software solution, be it a framework a util or just a func that does something useful that is used by multiple clients, i don’t want its intention to be watered down by years of refactoring. Its intent should remain clear. This is easily done using comments the declare a function. I don’t see what all the fuss is about

  2. I thought this was already agreed upon ages ago? Code and it’s tests should be enough to explain what is going on, if not then it probably needs a refactor. Comments are for when you’re doing something that may appear slightly weird but is actually done that way for a good reason such as performance.

    • Dan — I think the idea, (e.g. The DHH quote) is something we all kind of get. But workin’ in that nasty real world, fixing bugs in code from 6 years ago by a guy who just graduated from college, or even something new … it’s never as pure and virtuous as all that. When faced with reality of time pressure, forced compromise, close enough for now and all other such evils, add a comment.

  3. At an absolute minimum, there’s at least one other category of comment which is : “there’s something really non-obvious here, so don’t waste days trying to fix it”. This happens with various kinds of optimization, bugs in vendor libraries, and some other cases. Anyone who doesn’t understand the value of this kind of comment hasn’t been coding for very long.

    • Yes, I was about to comment this when I saw yours. Especially in high performance code, sometimes you do something unreadable which just needs explanation.

  4. I find that the only times I add comments are when the code doesn’t make sense on its own, such as when I have to write hacks / workarounds for whatever reason.

    Other than that, I completely agree.

  5. It depends is right. I comment the oddities — the hacks we need to make when working in the real world or to satisfy some stupid requirement. I’ll typically add the bug number for context. But it’s typical programmer hubris to believe your names are so great that everyone will understand them. I agree with the DHH idea, which for me boils down to: if you can’t come up with a good name, you’re doing something the wrong way. Still, the occasional hint before a method, an inline comment when you use a non-standard approach, or sometimes a bit of humor makes the lives of the poor miserable saps that have to read my horrid code that much easier.

    I also used to do what I suppose would be called CDD today — write my comments first and fill in the code to do it after. I actually think that’s about the right density of comment, and like the CSS example, helps keep code organized.

  6. Comments are visual markers to code. It helps delimit the beginning and end of functions for example. Of course they help to explain the code too.

  7. As someone who didn’t know the purpose of your code right away, your code comment WAS helpful. Your comment let me know that this was for baseball and that we were creating a lineup up of players.

    I do believe that DRY should extend to code comments, but that code comments are very important. In most popular frameworks, well commented classes and methods are almost always present. If added properly, your IDE will show you exactly what a method does and why when you scroll over it. Also, if you need to generate API docs, it’s your comments that will get scraped (the ones you specify, at least).

    I would reformat your code comment to include at the very least the what and why. I would remove the focus on what specific data structures you are passing in/out. The developer can see that just by looking at the parameters.


    Assign each baseball player an order in a lineup. The lineup determines when each player gets to bat.

    I would also rename your function to assign_lineup.

  8. Comments are like landmarks on the highway. They may not contain verbal meaning, but they add visual impact, and make it easier to navigate.

  9. Oh, how many times people left a comment describing something and then that something changes but the comment stayed now making no sense.
    I’m not going on saying that 100% don’t write comments, just 99%. You should be testing your code, and testing will tell you what your code is doing.
    And should write methods and lines of code that are readable. I know some ppl like to chain code like there is no tomorrow… super pro..l33t..a pitty no one else can read without that is a major headache.
    Variable naming.
    Method naming. Will help more than comments. You can laugh of public setToastForToasterToBeAbsoluteInTheContextOfCartoons() …ya ok making no sense here.. but don’t be shy with the length of names. If you’re minnifying your code, it will be names something like a() anyways.


Please enter your comment!
Please enter your name here