Not all comments have the same purpose. Understanding the different purposes that comments can fulfill can help you both write better comments and leverage existing comments more effectively.

Navigating Code

Using comments to help navigate code is an often underappreciated use of comments, but it is incredibly important for maintaining large codebases over time and onboarding new developers. There are multiple ways in which comments can be used to help navigate code.

One of the first and most important ways that comments can assist in navigating a code is by giving overviews of a codebase (or large sections of a codebase). When faced with a large and complex codebase, it's easy to get lost in the details. Overview comments can serve as a map, guiding developers through the code’s structure and organization, making it easier to understand how different components fit together. By reading such comments, developers can quickly grasp the overall architecture of the system and identify the key modules, classes, etc. that are relevant to their task (and ignore parts that might be irrelevant). Such overview documentation is also important in understanding and preserving the architecture and design of a large software system.

Comments can also help in navigating smaller sections of code. Think of code within a class or function like sections of a book. “Section headings” can help readers quickly find what they are looking for without having to read hundreds of lines. “MAJOR” comments are one technique to realize these benefits in code.

Using Code

To build larger and more sophisticated programs, developers will need to build upon the work of other developers - either by leveraging third-party code or internally-developed code from other team members. In either case, it is important for developers to know how to use that code.

Code will typically have all sorts of limitations, restrictions, caveats, etc. about what it can/can’t handle. These are important to know for programmers to successfully use the interface provided by a class, function, etc. You don’t want to cause them pain by leaving out information that could result in bugs in their code or waste their time trying to guess/test their way to correct answers. Provide the information for them. Comments can provide guidance on how to use the code, including examples, usage notes, and warnings about potential pitfalls.

Many documentation generator tools can extract comments from code to create web pages for interface documentation. While specifics may vary, documentation generators tend to support a standard syntax that can be used for documenting key interfaces. Below are examples of what function documentation documentation can look like for some different documentation generator styles across multiple languages:

Using such a documentation style helps ensure that the essential elements of using an interface are documented and provides a natural place to add in all of the weird usage quirks that another developer may need to be aware of. Our section on documenting code interfaces will leverage many of these styles.

Maintaining Code

Finally, comments can play a critical role in maintaining the code over time. When developers make changes to the code, they often need to understand the context and history behind the original implementation. Comments can provide this context, explaining why certain design decisions were made and how they relate to the overall architecture of the system.

For example, comments can be used to document the rationale behind implementation choices, including trade-offs and compromises made along the way. This information can be especially helpful when refactoring or optimizing the code, clarifying the original intent and constraints. TODO markers can highlight unfinished work or important areas to revisit.

Comments written for the purpose of maintaining code may be written at a lower-level of abstraction or be more technical compared to other kinds of comments.

When writing comments for maintenance, be aware of questions that arise during development that won’t be self-evident from the code itself. These are likely to be the same questions that future maintainers will have. Minimize their pain and set them up for success by documenting what’s important so that they can get the insights they need. This is also beneficial for you, as it allows you to move on to new projects without being bogged down by questions about old code. Seek to transfer the wisdom and knowledge you gained from working on the code to others. We have numerous tips on comments specifically to support maintenance programmers.