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.”

Jordan Hudgens

view all post
Leave a comment
Pierre • 9 months ago

If you update the code, update the comments.

reply
Jordan Hudgens • 9 months ago

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.

reply
Arz • 9 months ago

So the solution to that is no comments at all?

reply
Jordan Hudgens • 9 months ago

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).

reply
Prathamesh Juvatkar • 9 months ago

And code comments disobey principle of software development "don't repeat yourself (DRY)"

reply
Jordan Hudgens • 9 months ago

Yes they do, that's a good point!

reply
baselab • 9 months ago

Can it be this simple?

reply
Clark Boden • 9 months ago

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.

reply
Jordan Hudgens • 9 months ago

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.

reply
Javier Pedreira • 9 months ago

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

reply
Clark Boden • 9 months ago

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

reply
Dan • 9 months ago

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.

reply
Jordan Hudgens • 9 months ago

You'd think so, but if you look at the comment thread on this article and on countless comments on it on the Hacker News page: https://news.ycombinator.com/item?id=12651874 it would seem that there is still quite a bit of debate on the subject.

reply
Tom Harrison • 9 months ago

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.

reply
Vijay • 9 months ago

To automatically add comments to your JavaScipt code, try https://www.npmjs.com/package/commentify

reply
Jordan Hudgens • 9 months ago

Thanks for sharing that Vijay!

reply
Josh • 9 months ago

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.

reply
Nick • 9 months ago

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.

reply
Gal • 9 months ago

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.

reply
Tom Harrison • 9 months ago

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.

reply
Rafael Zarembksi • 8 months ago

My co-worker always write comments like: // Destroy the object FreeAndNil(object); What´s the purpose of that? :D

reply
tom nguyen • 5 months ago

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.

reply
html • 1 month ago

Comments are visual markers to code. It helps delimit the beginning and end of functions for example. Of co html

reply

Please be polite. We appreciate that.

By Daniele Zedda • 18 February

← PREV POST

By Daniele Zedda • 18 February

NEXT POST → 34
Share on