Code comments are lame.
Code comments once served a critical purpose; adding context or explanation to a snippet of code. But this was back when programming languages were mostly esoteric, and the barrier to entry for writing code was extremely high.
Today, though, we have extremely expressive programming languages, like C# (especially since the addition of LINQ), Python, Kotlin, etc. that make code comments virtually obsolete. With a highly expressive language, nearly all comments become unnecessary, because it’s easy to write self-documenting code; the code is easy enough to understand at a glance that you don’t need comments anymore.
“You should always write your code as if comments didn’t exist.” — Jeff Atwood (source)
I’ll be writing most of my code examples in Kotlin because it’s one of my favorite languages, and I haven’t gotten to use it recently, but all these examples are applicable to any sufficiently expressive language.
Most of the time, comments in the implementation of a bit of code can be made unnecessary just by naming things better, and keeping your functions and methods small and focused on a single task. Let’s consider a simple example.
We’re working on a web application, and we want to implement a method to validate that a password meets certain required criteria. For this example, let’s say our criteria are:
- Must contain at least one uppercase letter and at least one lowercase letter
- Must contain one number
- Must not include whitespace
- Must contain one of the following special characters: ! # $ % ^ & *
- Must be between 8 and 20 digits
We could do it in very few lines of code with a complex regular expression:
Without those comments inside of the
isPasswordValid function, it’s really cryptic and almost impossible to tell what it’s doing without taking a ton of time to figure out that really complicated regular expression.
By splitting each password criterion into a distinct unit of work, the code and the regular expressions used in the code both become a lot clearer and easier for a reader to grok with just a glance.
The code is only a few more lines long, but is so much clearer at a glance that we don’t even need that huge comment block anymore. We’ve converted a comment telling us what the code is doing into code that tells us itself what it’s doing.
This is the most useless (and annoying) type of code comment. These are the type of comments where you can just remove the comment without even changing the code, and it’s still just as clear what the code is doing.
Let’s say we’re working on a command line tool grab some data from an API and write it to a file. We’ll need to ask the user for a file path to write the data to.
There’s a lot cluttering up this code, though. It may seem a bit complicated, but that’s just because of the comments. In situations like this, removing the comments can actually make the code less intimidating to a reader.
When you see a function defined as
writeJsonToFile(json: String, filePath: String), with no comments or explanation, what do you think it does? You can probably immediately understand that “it writes some JSON data to a file”. We can remove every single comment, and the code is still just as clear, readable, and understandable.
We didn’t change any of the code here, we just removed all the comments. Yet, it still seems less intimidating on your first read, right? Appropriately named variables and functions make all the comments completely redundant, so the comments were just clutter.
Exceptions to the Rule
The main exception to this is tooling-specific documentation comments, such as JSDoc and C# XML Documentation Comments. These types of comments provide popup API documentation via IntelliSense (or another autocomplete mechanism) in most IDEs and editors, like VS Code, Rider, and others.
Documentation comments also usually hook into documentation generator tools, like DocFX or Sandcastle, which can automatically generate HTML documentation web pages from your documentation comments.
In this example, the comment is warranted, because it prevents future developers from introducing bugs without realizing it by changing
return Number.isFinite(value); to just
Another common example is when you need to prevent bugs caused by Internet Explorer having different implementations of built-in functions than every other browser, because reasons. Let’s look at another example in TypeScript.
Once again, in this example, the comment prevents a future developer from unknowingly introducing Internet Explorer-specific bugs by changing this implementation to just
Modern programming languages have become so expressive that code comments are virtually obsolete, except in specific circumstances. The time has come to replace code comments with highly expressive, self-documenting code.
Top comments (7)
Apart from the reasons you gave, I would argue that unit tests also remove the need for comments in several situations.
Aside from all the benefits that unit tests bring, they also can clearly define the intent of each code block. In your regex example, I would say that even without refactoring the method to simpler regex expressions, you can have multiple tests that help understand what that method is validating.
And unlike comments, unit tests can be enforced to be valid and updated when the code changes.
That’s a very good point. The only caveat is that you have to actually open the separate file for the unit tests, which isn’t a big deal it’s just another level of separation between the code and it’s specifications.
You don't always need to. Many IDEs will run them in a window and display test names and failures. That can be explanatory enough in many cases
Oh my are there people who disagree :P
Of course code comments will be needed in some scenarios. But more often than not, they’re not needed, and about 95% of comments I see in practice are redundant, at least in my experience.
Completely agree. I think most of the time if you need to write a comment you've failed to write expressive code.
Airight, the title drew me in.
I agree, but the % of comments which are needless depends a lot on the the employer.