Self-documenting code

A comment that says what the code does is a name you haven’t written yet. When you find yourself writing // check if the user can edit this post above a tangle of boolean conditions, you have already named the concept — in the comment. The code below it is the unnamed implementation. Extracting that into canEdit(user, post) moves the name from a comment (which the compiler ignores and nobody refactors) into a function signature (which the compiler checks and every caller reads).

// before: the name lives in a comment the compiler can't enforce
// check if the user can edit this post
if (user.id === post.authorId || user.role === "admin") { /* ... */ }

// after: the name lives in code that reads itself
if (canEdit(user, post)) { /* ... */ }

The comment and the condition could drift apart; the function name and its body cannot. The what is now carried by structure, not prose.

A dense block annotated by “step” comments is several named steps in disguise. A classic shape is one long function with // step 1: …, // step 2: … comments breaking it into phases. Those comments are an admission that the block does several things and you felt the need to label them. Each label is a function name asking to exist.

// before — comments narrate a block that does too much
function publish(post: Post) {
  // validate the post is ready
  if (!post.title || !post.body) throw new Error("incomplete");
  if (post.body.length < 100) throw new Error("too short");
  // render markdown to html and strip scripts
  const html = sanitize(renderMarkdown(post.body));
  // write to the store and bump the index
  store.save({ ...post, html, status: "live" });
  searchIndex.add(post.id, post.title);
}

// after — each step comment becomes a name that reads itself
function publish(post: Post) {
  assertPublishable(post);
  const html = renderSafeHtml(post.body);
  persistAndIndex(post, html);
}

The second publish reads like the step comments did — except the names are now verified by the type system and reused wherever the same step recurs. The comments became the table of contents the function always wanted.

An explaining variable turns a cryptic expression into a sentence — no function needed. Extraction is not only about functions. When a condition or sub-expression needs a // because … to be legible, naming an intermediate value often carries the meaning more cheaply than a whole function would.

// before: a comment is propping up an unreadable condition
// only retry on transient network failures, not 4xx
if (err.code === "ECONNRESET" || err.code === "ETIMEDOUT" || (err.status >= 500 && err.status < 600)) {
  retry();
}

// after: names make the condition state its own intent
const isNetworkReset = err.code === "ECONNRESET" || err.code === "ETIMEDOUT";
const isServerError = err.status >= 500 && err.status < 600;
const isTransient = isNetworkReset || isServerError;
if (isTransient) retry();

The comment // only retry on transient failures is now redundant — if (isTransient) retry() says it in code. The explaining variable is the lightest extraction available: no new call, no jump to another file, just a name.

The comments that survive are the WHY — and self-documenting code makes them more visible, not fewer. Once the what is carried by names, the only comments left are the ones code structurally cannot express: why a surprising decision was made, a link to the ticket or RFC that justifies it, a non-obvious constraint, a workaround for a bug in something you don’t control. These are gold, because no amount of renaming can derive them from the code — they encode context that lives outside it.

// WHY survives: the code can't explain itself
// Stripe rounds half-up; we round half-even to match Finance's ledger.
// Changing this silently re-bills every subscription. See FIN-2231.
const cents = bankersRound(amount * 100);

// Safari <16 throws on structuredClone of a Blob; fall back. (bug: WK-204931)
const copy = canStructuredClone ? structuredClone(v) : deepCopy(v);

“Self-documenting” does not mean comment-free. It means the code carries the what so clearly that the surviving why-comments stand out instead of drowning in // increment i noise. A senior reviewer reads a file and every remaining comment earns its place.