How to write good code comments

Comments in source code are somewhat controversial. The idea behind writing comments is that they serve as a form of documentation that’s very close to the code. However, many programmers believe that writing comments is an anti-pattern and therefore should not be written at all.

While there is probably some merit to that point of view, there are definitely situations in which a comment can be helpful. This is why it’s important that as a programmer, you understand when and how you should write comments.

In this article I’ll discuss ten best practices for writing good comments. This list was compiled based on an extensive review of scientific literature about comments in source code and software documentation in general.

One of the most common criticism of comments is that they aren’t needed, as good code should be self-explanatory. This is true to some extent: there’s absolutely no need to comment simple getter and setter methods, and clean code is often self-explanatory.

Only write comments when you want to document something that cannot be (easily) deduced from the source code, or when you’re documenting a public API.

Comments should provide information on a higher abstraction level than that of the code it describes. Most people find code hard to understand because it’s low-level. Merely repeating the code in English, on that same abstraction level, therefore won’t be very helpful to a reader.

Try to write comments that describe concepts rather than the details of the implementation. The best places for such comments are above methods and classes (side note: And possibly even modules!).

A comment should not try to explain the what or how of a piece of code, but the why: while the first two can often be easily inferred from the code, the latter can only be guessed.

Sometimes it’s important to know why code is implemented in a certain way. Such information is easily lost over time, so if it’s not recorded in a comment a future developer may have to invest a large amount of time in rediscovering that lost knowledge.

I have mentioned several times now that you shouldn’t write comments that simply explain what the code does, because such comments are redundant. It’s true for most code, but there are exceptions.

Some code is by its nature hard to understand. Typical examples include optimisation, pathfinding and other mathematical algorithms, or code that intentionally does something unexpected. There is no amount of clean coding that you can do to magically make such algorithms easy to understand – the best you can do is write a comment that explains how the code works.

If the code is based on an existing algorithm you should always explicitly mention the name of the algorithm somewhere so that people can look it up. Similarly, if you based your code on a snippet from Stack Overflow, it’s generally a good idea to show where it came from.

Comments should document design decisions and closely related technical information, like requirements, assumptions or informal constraints like pre- and post-conditions.

Why? Because inferring design decisions and related information from source code can be difficult. One study in particular notes that developers often find such questions hard to answer without external help, which might no longer be available if the original designer or implementer of that code no longer works at the same organisation. Including such information in the comments therefore makes it easier for maintainers, external developers and testers to understand what a unit of code should and should not do.

A good comment should tell readers more about its surrounding context beyond the current unit of code. This helps developers understand what code is supposed to do and makes it less likely that bugs are (re)introduced.

For instance, it might tell you how a class cooperates with other classes, how the current unit fits into a larger process, point you to documentation with use cases, requirements and UI designs, or include a reference to a JIRA issue. Recording such information in a comment rather than a commit message makes it less likely that it’s “lost” over time.

Another commonly heard criticism about comments is that they are unreliable. Normally, whenever a change is made to source code the corresponding comments are updated as well. But this is not guaranteed to happen, as developers may lack the time or motivation to update comments, or simply forget to do so. When this happens, a comment might become misleading and even cause bugs!

Make sure you always check if you need to update a comment when you make a change to the code that’s being commented on.

Code can be hard to understand. Comments allow developers to provide explanations about their code in a more easily understandable way. For this to be possible, first and foremost the comment itself must be understandable. It probably shouldn’t come as a surprise, but it really helps a lot if a comment is easy to read:

• The comment needs to be written in a natural language (e.g. English) at a level that is appropriate for its target audience, i.e. not too high, but also not too low. Most comments should probably target junior developers with an undergraduate degree.

• The comment text should be free from linguistic mistakes (side note: I’ve seen so many comments that were essentially useless because no one clearly understood what they meant!).

• Avoid abbreviations unless literally everyone – even the new intern – already knows what they mean.

Moreover, try to keep your comments short and to the point. Comments that are too long take more time and concentration to read, and may piss off your fellow developers. As a rule of thumb, most comments that are written in English should be at most 30 words long.

It’s a best practice to use meaningful identifiers for names of classes, methods, attributes, variables, and so on. Good names often even make comments completely redundant. But sometimes you still need to write a comment. When you’re doing that, it doesn’t hurt to reuse the same terminology from the domain and other parts of the code. Using domain language in comments makes the code easier to understand, because it:

• creates a shared lexicon or vocabulary that facilitates communication among developers and other stakeholders;

• makes it easier to find related software artefacts, such as documentation and requirements;

• reinforces the cohesion of a class, so that readers can more easily understand it as a single unit; and

• implicitly makes clear that the comment is up-to-date with its comment when it uses the same terminology and identifiers.

Consistency is key, or so they say. When writing comments, it’s generally a good idea to follow conventions (side note: With the exception of the first example there’s very little empirical evidence that any of this actually matters, so this is probably just a case of mass cargo culting.):

• If a programming language requires that certain comments be written in a specific format (e.g. Javadoc), use that format;

• Comments are generally written in a “telegraphic” writing style that omits articles (“the”, “an”, “a”) (side note: I think it’s because many developers suck at writing, but 🤷‍♂️) and include source code identifiers;

• If almost every class in a project is commented, then yours should probably be too.