Commenting your code

Commenting your code is one of those things that everyone has a different opinion about.

Most of my programming experience come primarily from working on Ruby on Rails applications. One thing that’s emphasized in the Ruby on Rails community is the importance of writing clean and elegant code that speaks for itself.

In the jobs I’ve held, it generally meant that you shouldn’t be writing comments in your code. Instead, your code should speak for itself so that when another developer looks at it, they know what your code does by reading the code rather than having to read any accompanying comments.

My opinion on commenting code has been that you should be writing your code in a way that doesn’t need comments. This means descriptive variable names, method names, class names, and etc. However, I’ve had a few code reviews done on the projects I’ve worked on in the past few months where the feedback I received is that my code doesn’t have any comments and that I should start commenting my code more frequently.

So, should we comment our code, or should we not?

During the hand-off process of one of the projects I’ve completed, me and the client’s part-time CTO were conducting a code review. One of his immediate feedback was that I should have commented the code more. Me and him got to work over the few weeks after the initial code review and he proceeded to write comments on a lot of the pre-existing code. One example of his commenting on one of the methods was (note: this is just an example of the complexity of the code on hand, this isn’t the real code)

The original code didn’t have comments on it, but the code was commented once I began working with the client’s CTO.

Now, I think most developers will agree that the above method does not need to be commented at all. The name of the method clearly says what the method is intending to do, and ruby methods are named descriptive enough to signify to the developer what the “flatten” and the “sort” method should do. There is absolutely no reason to comment this method. In fact, commenting this method just makes the code more difficult to read since I have to now read over that “#” character in the method.

This reminded me into my first programming class in University where our assignments had categories where we would receive points for commenting our code. Yes, we got deducted points in our programming assignments if we didn’t comment our code, even if the program was trivial.

I thought that the majority of developers would agree with minimal commenting on code, and instead writing your code in a way that it speaks for itself, but after a few of these code review, I realized that there are developers out there who believe that commenting code is something that we should do as developers.

I don’t believe all commenting is bad. In fact, I do believe that there are times where commenting your code is necessary. However, you shouldn’t have to comment your code in 90% of the cases if you’re writing your code in a self-documenting manner. Here’s why I believe that you should opt for writing your code in a self documenting manner rather than commenting.

The computer doesn’t care about your comments

Yep, the computer doesn’t care about the comments in your code when it runs your program. The comments you write are for other humans, and….. it’s written by humans. Which means, we’ll forget to update our comments as we update our code.

Software projects have to constantly change to meet business needs. If your code depends on your comments to make sense, and the functionality of the code changes over time, someone will inevitably forget to update the comment that describes what the code is doing. Yes, the code will run even if you forget to update the comment, but the next developer who comes into the project will end up reading the outdated comments and misunderstand what the code is doing. And since the computer only runs your code and ignores your comments, it’ll be very difficult to understand what’s going on if there are any bugs and problems in your system.

I believe that this is the most important reason you should opt for writing self-documenting code rather than relying on comments. Some people might give arguments such as comments dirtying up your code, comments making your line of code longer, and etc. But at the end of the day, you want your code to speak for itself to better serve business needs, and to more correctly communicate the intention of the code to other developers. Using comments, especially to communicate the intention of the code to other developers is way too brittle.

So when should you comment your code?

There are times where I believe that it’s appropriate to comment your code. The main situation I can think of where commenting your code is appropriate is when the code your are writing is orchestrating some business rules with exceptions that may not be obvious to the developer reading the code.

For example, let’s say there’s a method in your code base that calculates the average of two numbers. Normally, you would sum the two numbers and divide the result by 2. But let’s say for example, you find that the method your looking at is dividing the result by 3. If there aren’t any comments, you would think that this was a bug. But let’s say this isn’t a bug and was intentional due to some weird funky business rule. This would be the perfect time to comment your code. So here’s an example.

If the comment wasn’t there, I would probably look at the code and go “huh, so I guess this is what’s causing the bug”. If this was intentional, and I “fix the bug”, I would cause even more bugs. However, if the comment was there, I would go “Okay, this is a little weird, but I guess this is how it’s supposed to work” and move onto other lines of code.


I strongly believe in writing self-descriptive code and only commenting it’s the only way of better communicating the purpose of the code. It better communicates the intention of the code, reduces potential for bugs, and turns your codebase into something like a blueprint/manual for the business it’s serving.