The Best Comments Are Not Notes, They Are Interfaces

May 09, 2026

11 min read

2 views

62%

When a comment is a waste of time, and when it is the whole point

What if the best comment in your code is the one that lets the reader stop reading your code?

That sounds wrong at first. Most of us were taught that comments are a necessary evil, a paper trail for people who could not be bothered to write clearer code. But that view misses something essential: a comment is not just an explanation. In the best cases, it is an interface. It does not merely describe what exists. It tells another mind how to use what exists, what assumptions are safe, and what would be a mistake.

This is why some comments age beautifully while others rot into lies. The difference is not verbosity. It is purpose. A good comment does one of a handful of precise jobs: it frames a black box, teaches a domain, records a decision, or warns of a constraint. A bad comment usually tries to do the job of the code itself, or worse, it tries to be a museum label on a living system.

Now add an apparently unrelated idea: a plugin setting that lets you choose which field gets a link appended to it. That sounds like a tiny convenience feature. But it reveals the same deeper principle. The most useful systems do not merely store information. They shape the path of attention. They decide where context lives, how it travels, and what future you will need in order to understand present you.

The deeper question connecting these ideas is simple but profound: how should a system tell the next person what kind of thinking it expects?

The real job of a comment is to reduce interpretive friction

Most discussions about comments focus on whether they are helpful or unnecessary. That is too shallow. The real issue is interpretive friction, the cost of figuring out how to think about something before you can safely change it.

Code is not just text. It is a set of commitments. Some commitments are obvious in the implementation itself. Others are not. A clean function name may tell you what the code does, but not why it does it that way. A comment can fill that gap by acting like a contract between the writer and the future reader.

Think of a function comment as a label on a drawer in a workshop. You do not need a miniature essay inside the drawer. You need enough information to know what belongs there and what does not. If the comment says, in effect, “treat this as a black box with these rules,” it has done something powerful. It has turned complexity into usability.

That is why the distinction between code and comment is not really about medium. It is about surface area for misunderstanding. A good comment narrows that surface. It prevents a reader from wasting cognitive cycles on questions that do not matter, or from making assumptions that are easy to make and hard to detect.

Consider a replication subsystem in a distributed database. The code may show message passing, retries, sequence numbers, and state transitions. But what you really need to know is the design logic: why this mechanism exists, why a simpler one was rejected, and what failure mode it protects against. Without that, a reader may look at the implementation and think, “This seems more complicated than necessary.” Sometimes that instinct is right. Often it is wrong. A design comment exists to answer that exact doubt.

The best comments do not say more than the code. They say the one thing the code cannot say clearly enough: what kind of reasoning the reader should use.

That distinction matters because readers come with different intentions. One person wants to modify behavior. Another wants to reuse a function. Another wants to learn the domain. A comment can be a bridge to any of those goals. But it must know which bridge it is building.

Comments as teacher, not transcript

There is a particularly underrated kind of comment: the one that teaches the domain rather than the line of code. A comment on a data structure may not only explain a pointer invariant. It may teach the logic of interval trees, skip lists, replication, compaction, or any other specialized idea that turns code into a small chapter of a larger discipline.

This is where many teams miss the chance to compound knowledge. They use comments to restate implementation details that are already obvious to anyone willing to read the code. But the highest value comment often answers a higher order question: what field of knowledge does this code belong to, and what concept from that field should I borrow to understand it?

Imagine a new engineer reading a memory allocator. A trivial comment says, “increment the free list pointer.” A teacher comment says, “this allocator uses segregated free lists to reduce fragmentation, so small blocks are handled differently from large ones.” One comment repeats action. The other opens a mental model.

That is a huge difference. Repetition has short half-life. A mental model has compound interest.

This is also why “why comments” matter so much. When an implementation looks deceptively simple, future readers often distrust it. They should. Simplicity can mean elegance, or it can mean a missing constraint. A good why comment records the competing alternatives and explains why the chosen path was sufficient. It is not defensive prose. It is archaeology for decision making.

A design team that made a minimal choice instead of a clever one can save future selves from a very expensive false optimization. Suppose a cache eviction strategy appears almost too basic. A comment that says, “We considered LFU and adaptive policies, but the workload is bursty and the simpler policy avoids churn without measurable regressions,” can prevent a future engineer from “improving” the system into a worse one. The comment does not glorify simplicity. It explains the boundary conditions that made simplicity intelligent.

This is one of the most underappreciated forms of engineering memory: not storing facts, but storing reasons under uncertainty.

The note field is a miniature philosophy of context

Now the seemingly small matter of a plugin setting. If a tool lets you choose which field gets a link appended to it, that is not just a UI preference. It is a statement that context has multiple valid homes.

Where should a backlink live? In a note body, a metadata field, a linked reference section, an annotation column? The answer depends on the kind of future use you expect. If the link belongs where you will read it while writing, it becomes part of the thought process. If it belongs in a dedicated field, it becomes searchable structure. If it belongs in a comment-like area, it becomes an explanatory aside.

This is exactly the same problem as comment taxonomy in code, only in a different medium. Some context is inline API documentation. Some is file-level design rationale. Some is a guide for navigating a complex artifact. Some is a checklist to ensure critical steps are never skipped. The storage choice determines the cognitive function.

A note field in a knowledge system is often treated as an afterthought, just a bucket for extra text. But the option to control where a link goes reminds us that placement matters as much as content. A link inside the wrong field can be noise. The same link in the right field can become a cue, a reminder, or a proof trail.

This gives us a useful framework: every piece of context should answer one of three questions.

What is this? This is identification, close to function comments.
Why is it this way? This is rationale, close to design and why comments.
How should I use it? This is guidance, close to teacher and checklist comments.

Most bad documentation fails because it answers the wrong question. It explains what the reader can already see and ignores the question the reader actually has.

Context is not valuable because it is attached. It is valuable because it is placed where a future mind can use it without friction.

That is the hidden commonality between code comments and note-link placement. Both are decisions about where understanding lives.

A practical framework: the five kinds of context worth writing

If you want to write comments or notes that survive contact with the future, stop asking, “Should I comment this?” Ask instead, “What kind of cognitive work should this text do?”

Here is a practical framework that emerges from the intersection of these ideas.

1. Black box context

Use this when the reader should trust the abstraction without reopening it.

Example: “Returns a stable snapshot of active sessions. The caller must not mutate the returned list.”

This kind of context tells the reader what contract to rely on. It saves time and prevents misuse.

2. Rationale context

Use this when the choice is not obvious and alternatives mattered.

Example: “We use a simple round robin policy here because the workload is homogeneous and more complex policies caused thrashing under peak load.”

This protects against accidental redesign by future optimizers.

3. Domain context

Use this when the code depends on specialized knowledge.

Example: “This uses a tombstone approach because deletions in eventually consistent systems must preserve causality information.”

This turns cryptic implementation into teachable system design.

4. Navigation context

Use this when the reader needs a map, not a detail.

Example: “Start with the request handler, then follow the retry policy, then read the persistence boundary.”

This is the equivalent of a good table of contents. In notes, this is often where a link is most useful. In code, it might be a file header or module overview.

5. Constraint context

Use this when failure would be costly and the rule must be remembered.

Example: “Never bypass this validator, because downstream indexing assumes normalized timestamps.”

This is where checklists and warnings matter. These comments are not decorative. They are guardrails.

The key insight is that not all context belongs in the same place, and not all context serves the same reader. If you know the intended cognitive job, you can write shorter, clearer, and more durable explanations.

The deeper discipline: document the boundary between certainty and convenience

The strongest code comment, the smartest note placement, and the most useful link field all share a deeper virtue: they preserve the boundary between what is known, what is assumed, and what is merely convenient.

This boundary is where projects either mature or decay.

When a system grows, people begin to rely on tribal knowledge. They remember why something was done a certain way, but only vaguely. They also begin to confuse local convenience with global truth. A comment can prevent that drift if it captures the exact status of an idea. Is this an invariant? A historical artifact? A temporary workaround? A deliberate simplification?

That distinction is priceless. A temporary workaround presented as a permanent rule becomes technical debt. A deliberate simplification mistaken for laziness becomes a target for needless complexity. A historical artifact left undocumented becomes folklore, and folklore is a terrible storage format for engineering intent.

In that sense, good commentary is not just documentation. It is epistemic hygiene. It keeps a system honest about what it knows.

The same applies to knowledge tools. If every link is appended in the same field, the system may become mechanically consistent but cognitively flat. If links are placed where they serve a function, they become part of a living structure. The note system then behaves less like a dumping ground and more like a map of thought.

This is why the most effective comments often feel almost invisible. They are not meant to be admired. They are meant to disappear into the reader’s workflow at exactly the moment they are needed. That is the highest compliment you can pay a piece of explanatory text: it becomes part of how someone thinks.

Key Takeaways

Write comments as interfaces, not transcripts. A good comment tells the reader how to reason about the code, not just what the code says.
Separate rationale from implementation. If a choice is non-obvious, preserve the reason, the tradeoffs, and the alternative paths you rejected.
Teach the domain when the code depends on it. Do not just explain lines. Explain the mental model the reader needs to understand the lines.
Place context where it will be used. In notes systems as in code, the location of a link or explanation is part of its meaning.
Protect the boundary between truth, assumption, and convenience. Good documentation keeps future readers from mistaking a workaround for a law.

Conclusion: the best documentation changes what future people think is obvious

The real power of comments is not that they add information. It is that they reshape what a future reader considers obvious.

That may be the most important thing any explanatory system can do. Code comments, note links, file headers, and metadata fields all participate in the same quiet project: they reduce the cost of correct understanding. They help a future mind skip the wrong questions, land on the right abstractions, and trust the right constraints.

So the next time you write a comment or choose where a link should live, do not ask whether it is redundant. Ask whether it helps the next person cross the gap between seeing and understanding. If it does, then it is not clutter. It is design.

And once you see comments that way, you stop thinking of them as annotations on the system. You start seeing them as the system’s memory of how to be used well.