“Heap, Heap, Array!”

How to write good code comments

In this latest instalment of “Things That People Don’t Want To Bother With” I discuss best practices for writing comments in source code.

Moses holding two tables containing the Ten Commandments. One tablet lies broken on the ground.
The Lord, the Lord Jehovah has given unto you these fifteen… Oy! Ten! Ten commentments for all to obey!

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.

Best practices


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.

Only comment when necessary


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.

Keep comments high-level


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 .

Describe the purpose


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.

Explain code that is hard to understand


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.

Document design decisions


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.

Provide context


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.

Keep comments up-to-date


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.

Make comments easy to read


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 .

  • 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.

Use domain language


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


Consistency is key, or so they say. When writing comments, :

  • 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 and include source code identifiers;

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