Write Code Not Comments

Whether code comments are advantageous or not tends to be a contentious issue. As a developer, I personally subscribe to the philosophy laid out by Robert C. Martin in his book Clean Code: A Handbook of Agile Software Craftsmanship. I feel that code comments are something that can be safely avoided if you’re practicing writing good code. For those new to programming I highly recommend reading this book, particularly the chapter pertaining to comments.

The viewpoint of code comments being problematic is not universally accepted. Nor is it new. Nevertheless, in my decade of experience as a Java developer, it’s something I’ve come to personally agree with more and more. In this post, I’ll discuss why I think comments can be problematic, demonstrate why expressive code is a good alternative, and provide some personal examples I’ve seen of both helpful and unhelpful comments.

Write Code Not Comments

“The older a comment is, and the farther away it is from the code it describes, the more likely it is to be just plain wrong.”
 — Robert C. Martin, “Clean Code: A Handbook of Agile Software Craftsmanship”

To clarify — when I say “write code not comments” I am not advocating for less information in the code. I’m advocating that information be expressed as code as much as possible. In other words, minimal commenting in favor of expressive code.


At best, comments are a duplication of information — which DRY practitioners oppose — and at worst they are misinformation. After all, even the best comment can become a false statement if the code is modified but the comment is not:

This example is trivial but it illustrates the point. Why not lose the comment? Or even move the code into a method called setDefaults() so it’s clear what is going on?

Also, comments don’t compile and they can’t be unit tested so there’s no way to verify anything you read in a comment. It’s better to understand the code because the code is what actually gets executed.

“The proper use of comments is to compensate for our failure to express ourself in code.”
 — Robert C. Martin, “Clean Code: A Handbook of Agile Software Craftsmanship”

Comments are a failure to express an idea in code. Every variable name, method name, and class name is an opportunity to express an idea. Almost anything you write in a comment can be expressed in these names:

If you have too much to say in a single name, you can break the code into smaller pieces like so:

Some Other Less-Than-Ideal Uses of Comments

Comments are drilled into our brains from the earliest stages of learning, including the tutorials and ‘hello world’ programs we often start with. I remember in one college-level computer science course being graded on the quality of my comments — the more comments I wrote, the higher the grade would likely be.

It’s easy to see why many developers tend to start off writing lots of comments. But when working on a ‘hello word’ project or a school project, those comments are for a short-term benefit. The code is thrown away when you’re done with it (e.g. at the end of the semester) and no one has to maintain it.

At work, your code may become part of a production system that hangs around for years and is maintained by many other developers. In this case, it’s better to emphasize good, readable code over comments up front so it can be easily refactored by your future teammates.

In older code, I’ve seen comments added at the top of the file to track version history — authors, dates, etc. This is unnecessary if you use a modern version control system like Git or Subversion, which tracks all this information for you.

In a case where the author is prominently displayed as a standalone comment, it feels to me like ‘marking your territory’ which I’m not a big fan of (code ownership = usually bad). Odds are that others have contributed (or will contribute), but they may not be comfortable with removing your name.

Comments are often used to comment out old or unused code. Personally, I’m firmly against this practice as it adds clutter that future maintainers may avoid dealing with. After all, they won’t know why it was commented out! If the code is not worthy of being committed in non-commented-out form, then it should be deleted. Keeping your code free of commented-out sections saves the reader time by allowing them to focus only on the code that matters.

Are Comments Necessary?

In some cases, you may be forced to do something programmatically that defies normal logic. For example, you may be implementing a work-around to a bug or some other necessary hack. This is an area where you may want to explain why you are doing something unexpected. In this case, try to isolate your hack/comment into its own method so it can be self-contained and not bleed into the surrounding code.

Comments are useful when your main product is your code. For example, you may be writing an API that others will integrate with their own code. In that case you may want to document method inputs/outputs, edge cases, etc. (Javadocs are a good example), especially if they will not have access to the original source code.

(You can view some examples of API code documentation on the Capital One DevExchange site)

Final Thoughts

Comments are the last place I want to look to learn about what the code is doing. When I look at a piece of code for the first time and see lots of comments, commented-out sections, and poorly named methods, it gives me an impression of less-than-professional quality.

Again, I’m not saying documentation is bad or that you should never document what you’re doing. Rather I’m saying I would prefer readable code with good naming over code with lots of comments. In other words, a form of documentation that doesn’t become out of date with the code.

DISCLOSURE STATEMENT: These opinions are those of the author. Unless noted otherwise in this post, Capital One is not affiliated with, nor is it endorsed by, any of the companies mentioned. All trademarks and other intellectual property used or displayed are the ownership of their respective owners. This article is © 2017 Capital One.

For more on APIs, open source, community events, and developer culture at Capital One, visit DevExchange, our one-stop developer portal.developer.capitalone.com/

Additional Links

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.

The author has chosen not to show responses on this story. You can still respond by clicking the response bubble.