Code Comments Are Stupid
By: Mat Jones
Tags: JavaScript, Programming, Code, Comments, Clean Code

Implementation Comments

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:

A great way to make enemies is to make sure nobody else can understand your code.

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.

A few more lines of code can go a long way for clarity.

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.

Redundant Comments

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.

Seems good… or not?

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.

Its still just as easy to understand this code without the comments.

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

Documentation Comments

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.

Clarification Comments

Sometimes, there is an obvious solution that seems simpler or better, but there is a specific reason the developer chose not to use that solution. I’ve found this to be extremely common in JavaScript. Let’s take a look at an example. We’ll use TypeScript to help make things a bit clearer.

Finally, an appropriate place for a comment.

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 return isFinite(value);

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.

Internet Explorer is a scourge on the world.