When Are Code Comments Worth It? Exploring the Debate on Self‑Documenting Code

Preface

On a recent drive home, a driver complained about "cut‑ins" and I asked if anything was worse; he replied, "not letting yourself be cut‑in." Similarly, programmers despise missing comments and, even more, being forced to write them.

The Meaning of Comments

Comments explain and document code to improve readability and understandability. They are stripped by the pre‑processor or compiler. As Robert C. Martin notes, comments compensate for our failure to express intent directly in code.

"The proper use of comments is to compensate for our failure to express ourselves in code." – Robert C. Martin, Clean Code

Controversy and Disagreement

The origin of comments is ancient, but their usage remains hotly debated. Some claim perfect code needs no comments, while others argue that without comments even good code can be hard to grasp.

"If our programming languages were expressive enough, or if we had the talent to subtly wield those languages to express our intent, we would not need comments very much—perhaps not at all." – Robert C. Martin, Clean Code

Comments as a Lifeline for Bad Code

Zero comments often accompany poorly written code, turning the code into a "secret between me and God." Adding clear comments to complex business logic can make the intent obvious and reduce the cognitive load on readers.

"You might think the purpose of commenting is to 'explain what the code does', but that is just a small part of it. The purpose of commenting is to help the reader know as much as the writer did." – Dustin Boswell, The Art of Readable Code

Utopian Software Design

Some believe that "good code is self‑documenting" is a beautiful myth. While better naming, structure, and design reduce the need for comments, certain domain knowledge, design decisions, or historical context cannot be expressed in code alone.

Best Companion for Good Code

Well‑written code should minimize redundant comments, but useful comments can act as a "best companion" by clarifying intent, documenting edge cases, or explaining non‑obvious constants and algorithms.

The True Place of Comments

Complex business logic, such as Spring's bean retrieval code, benefits from concise comments that explain the flow and rationale. Similarly, JDK examples like Long.reverse and HashMap.TREEIFY_THRESHOLD show how comments can justify magic numbers and algorithmic choices.

/**
 * Returns the value obtained by reversing the order of the bits in the
 * two's complement binary representation of the specified {@code long}
 * value.
 */
public static long reverse(long i) {
    i = (i & 0x5555555555555555L) << 1 | (i >>> 1) & 0x5555555555555555L;
    i = (i & 0x3333333333333333L) << 2 | (i >>> 2) & 0x3333333333333333L;
    i = (i & 0x0f0f0f0f0f0f0f0fL) << 4 | (i >>> 4) & 0x0f0f0f0f0f0f0f0fL;
    i = (i & 0x00ff00ff00ff00ffL) << 8 | (i >>> 8) & 0x00ff00ff00ff00ffL;
    i = (i << 48) | ((i & 0xffff0000L) << 16) |
        ((i >>> 16) & 0xffff0000L) | (i >>> 48);
    return i;
}

/**
 * The bin count threshold for using a tree rather than list for a bin.
 * Bins are converted to trees when adding an element to a bin with at
 * least this many nodes. The value must be greater than 2 and should be
 * at least 8 to mesh with assumptions in tree removal about conversion
 * back to plain bins upon shrinkage.
 */
static final int TREEIFY_THRESHOLD = 8;

Conclusion

Comments do not prevent elegant code; they are an integral part of software development. When code cannot fully convey intent, thoughtful comments add clarity, aid maintenance, and preserve knowledge across evolving codebases.