Introduction

“Documentation” is a common topic of discussion in software projects. Many different kinds of documentation are frequently created for a software project - requirements documentation, design documentation, in-code comments, end-user product manuals, etc.

This training focuses on the the most common form of documentation for most programmers - comments within the code itself. Many years of experience reading, writing, and maintaining code have revealed many benefits to comments, if done well. Well-crafted documentation helps with navigating a codebase, understanding the reasoning behind design decisions, and making informed changes with confidence.

Not all comments are created equal. Some comments are valuable, providing crucial context and insights that would be lost to time without them. Others are merely redundant, repeating what the code already says, or even misleading, adding confusion rather than clarity.

In this training, you’ll learn to master the craft of writing high-quality documentation in support of codebases that remain maintainable over long stretches of time. We'll discuss the different purposes of comments, the characteristics of valuable versus harmful comments, and the importance of commenting at the right level of abstraction. We'll also delve into the best practices for structuring comments, maintaining them over time, and using them to document both small and large parts of code. By the end of this training, you'll be equipped with the knowledge to write documentation that makes your code more readable, understandable, and maintainable - a crucial step towards creating software that stands the test of time.

Why Comments Are Needed

Some may wonder, “why are comments needed?” This is a worthwhile question to ask, as we don’t want to spend our time writing a ton of comments if they’re not valuable. There are several reasons why comments are needed when considering long-term maintainability of codebases.

A Goal of Self-Documenting Code

“Self-documenting code” is an often-used phrase that can be interpreted in at least two ways:

• Just the code itself being clear enough to serve as its own documentation, eliminating the need for comments.

• All of the text in the code files (both actual executable code + comments) provides enough documentation - in other words, someone grabbing all of the original source code files for a project would have all of the documentation self-contained in those files (close to the relevant code).

Both interpretations have merit and are worth exploring.

True “self-documenting code” - where just the code itself provides sufficient documentation - through good design, variable names, coding conventions, and easy-to-understand approaches is a noble goal. This pursuit will indeed lead to more readable and maintainable code. After all, the code itself is what the computer will execute - it is the only reliable source of truth as to what some software is doing. You want this code itself to communicate as much as possible to readers.

However, code itself has limitations in what it can convey. Code is translated into instructions with relatively simple vocabulary for computers to execute. Even higher-level languages have syntax constraints that limit what they can express compared to human languages, many programmers will generally be more fluent in their native human languages.

That’s where comments come in. They allow us to express things that code itself may not be able to express. Placing these comments in the same files directly alongside the code is beneficial - it brings the documentation close to where programmers are working, thus making the overall code files for a software project “self-documenting.”

Things Code Itself Cannot Say

What are some things that code itself cannot say?

There are many things that code itself cannot say, but code is fundamentally limited in that it primarily describes what is happening. Code can’t really communicate why something is the way it is.

While you can use variable names, functions, and other coding elements to provide some context, there are limitations to how much information you can convey through code alone.

For example, variable names can become impractical if they are too long - becoming too much for a person to keep in his/her head at once. Even if a given variable name itself isn’t too long, difficulties could arise when trying to understand the larger code where that variable might be used.

Code itself can be challenging enough to comprehend, so being able to focus on the what itself can be helpful at times. The why is important, but often people need to be reminded of that once (or a relatively few number of times) before diving into detailed code itself.

There are many different things code cannot adequately communicate by itself:

• Why software is doing something in particular to meet end-user needs

• The intent behind what a programmer was trying to accomplish in some code

• Why a programmer wrote code a certain way

• Historical context for how code may have changed/evolved over time

• Considerations when making future updates

The list goes on-and-on, and we’ll explore many of these throughout this training. Not being restricted to limitations of programming language syntax, this information can be better expressed in natural human language via comments.

Helping People Better Understand Code

Even in the most well-written code, programming language syntax can limit effective communication. Code isn’t necessarily the most intuitive way for many humans to understand complex topics. Rewriting things in more natural human language can sometimes better clarify what is going on with some piece of code. If there’s uncertainty, reinforcing things with comments can help other programmers be confident when making changes or debugging.

Comments can also benefit people outside of a programming team. Modern software projects involve many roles, and not everyone has deep technical expertise. Well-written comments can help testers, manual writers, and others understand the software better and collaborate more effectively with the programming team.

Commenting is fundamentally about enhancing human understanding of code. Doing this well is a key ingredient of maintainable codebases. Make sure your comments enhance the understanding of code for its readers. Items described in the previous section that code cannot communicate can be particularly illuminating.