Comments Suck and You Probably Write Too Many

#engineeringpractices #cleancode #go #comments

The post Comments Suck and You Probably Write Too Many first appeared on Qvault.

I often hear that we need more and better comments in the code we write. In my experience at previous companies as well as at Qvault, we often need better comments, we rarely need more, and often we need less. Before you crucify me for my sacrilege, let me explain.

#1 – Incorrect Comments

Incorrect documentation is worse than no documentation, and redundant documentation is worthless. Let’s remove the chaff. Developers typically (and rightly) take the path of least resistance when trying to figure out what a piece of code is doing. When provided a function with a comment, many developers will read the comment instead of reading the code itself, especially if the function is long and complex. Let’s take a look at this trivial example:

// replace changes all the commas in the text to colons
func replace(s string) string {
    strings.Replace("s", ",", " ", -1)
}

When another developer decides to use this function, they expect that commas will be replaced by colons. As this code clearly shows, however, the commas will be replaced by spaces. Because of the incorrect comment, a reader may take the comment at its word and introduce a bug, they may “fix” the comment and leave an existing bug, or they may “fix” the code and introduce a new bug. The point is, a bug is very likely to be produced if the reader isn’t careful.

The solution would be to give the function a more descriptive name and delete the comment entirely.

func replaceCommasWithSpaces(s string) string {
    strings.Replace("s", ",", " ", -1)
}

#2 – Redundant Comments

It would have been strictly better to omit the comment in the example above entirely. The developer would have been forced to go to the single source of truth (the code) and would have interpreted the meaning correctly.

Comments and documentation should, to some extent, follow the DRY principle (don’t repeat yourself). If the code clearly states what is happening, why add a comment? If functionality changes then two things need to be updated! If the code doesn’t clearly state what is happening, then a developer’s first instinct should be to make the code more readable, not to add a comment.

Redundancy is also quite simply a waste of time. Developers remain best-utilized writing code, architecting systems, and creating tests. We should only write documentation when absolutely necessary.

#3 – Comments for the Outside World – AKA Documentation

As we try to weigh the necessity of adding a comment to code, we need to take into account that it’s more likely that a comment is needed if it exists at an architectural boundary. For example, when writing a package or library we don’t want the users (other developers) of our code to have to worry about the internal workings. The function and class names along will well-written comments (or API docs as the case may be) should be all they need to understand how to use our APIs.

#4 – Comments Should Explain ‘Why’ not ‘How’

Comments and documents that explain why something is happening are quite important and don’t apply to any of the previous criticisms I’ve made of comments. Comments that explain how the code works are often redundant and lazy. For example,

func cleanInput(input string){
    input = strings.ReplaceAll(input, "^", "-")
    input = strings.ReplaceAll(input, "?", "_")
    ...
}

Here it is clear by reading the code that all instances of carets and question marks are being replaced by dashes and underscores… but why?

func cleanInput(input string){
    // clean input so that it can be used in a regex
    input = strings.ReplaceAll(input, "^", "-")
    input = strings.ReplaceAll(input, "?", "_")
    ...
}

A comment that explains that carets and question marks are removed for later use in a regex is an example of a good comment because it’s often hard to express the “why” in code.

Hopefully, these rules of thumb help when you are trying to clean up your code and write better comments. As always, let me know on Twitter if you agree or disagree.

Thanks For Reading!

Take some coding courses on our new platform

Subscribe to our Newsletter for more programming articles

Top comments (5)

PhyberApex • Nov 11 '20

I completely disagree. Your first example is just way to forced and imho not applicable at all. Why was that comment written wrong? Wouldn't the dev then also name the function wrong? If the function is named wrong the same applies as it did for the wrong comment.

The example with comment why and not how, I can get behind somewhat. Although again a bad example imho. As that comment to why should not be placed in the function but where it is used instead. Because if the comment is added within the function you could easily use it at someplace else where you have a second use case for the same functionality. If the first use case now changes a dev might be inclined to just change that function because it states the use case in the comment. Maybe breaking that second use case.

I agree we need good comments but in my experience I never came across a piece of code and thought to myself: "That's to many comments". So I don't think a call for action for less comments is what we need.

~Cheers

mattother • Nov 11 '20

Usually it's not that the comment is written wrong, but that the code changes over time and the comment isn't updated to reflect that. I'm sure somebody will argue "well don't do that", but that doesn't really reflect the reality of the situation most of the time.

Usually if the code is self descriptive it's better because then it's an atomic operation. As the code changes the high-level descriptor of what that code is doing also changes (hopefully anyways).

Either way, my point isn't to defend or oppose the article, but just to point out that incorrect comments are a very real problem on projects.