Why Not Comments

Original Article ↗ Hacker News Discussion ↗

Debate over so‑called “why‑not comments” – notes in code that explain why the obvious or more efficient approach wasn’t taken – highlights longstanding tensions around how software should be documented. Many engineers argue these comments are invaluable for future maintainers, capturing constraints, trade‑offs, and historical quirks that can’t be expressed in code alone, while others worry about clutter and staleness and prefer relying on clear naming, tests, commit messages, or design documents. The exchange also touches on style issues like overly long identifiers, title ambiguity, and the limits of “self‑documenting” code, but there is broad agreement that thoughtfully explaining non‑obvious decisions greatly improves maintainability.

Title and Framing

  • Many note the title is intentionally ambiguous wordplay: “Why-Not Comments” (explain why you didn’t do X) vs “Why not comments?” (anti-comment stance).
  • Several argue a hyphen (“Why-not”) would reduce ambiguity, but others like the double meaning.
  • This leads into broader talk about English compound words, hyphens, and deliberate ambiguity in titles.

When Comments Are Valuable

  • Strong support for “why” and “why not” comments:
    • Explain non-obvious tradeoffs (e.g., slow-but-simple algorithms when N is small).
    • Document rejected alternatives and constraints (customer quirks, legacy expectations, performance ceilings).
    • Capture domain or business logic that isn’t obvious from code alone.
    • Warn future maintainers about “obviously better” refactors that have already failed.
  • Many frame comments as “apologies” or breadcrumbs for future maintainers, often one’s own future self.
  • Common rule-of-thumb: comment anything surprising, non‑naive, or that previously required explanation in code review.

Concerns About Comments

  • Repeated worry that comments go stale, drift from the code, and become “lies waiting to happen.”
  • Some argue misleading comments are worse than none; others say the hours saved by any reasonable comments far outweigh rare harms.
  • Several emphasize that comments must be maintained and reviewed like code; ignoring changed comments is called unprofessional.

Alternatives and Complements to Comments

  • Git commit messages, ADRs, and design docs can capture “why not” at higher levels, but:
    • Many note commit messages are often low quality in fast-paced teams.
    • External docs easily get lost or outdated compared to inline comments.
  • Tests are praised as executable documentation but can also drift or be “fixed to pass” incorrectly.
  • Debug logging and runtime checks (e.g., warn when N exceeds assumed bounds) are suggested as dynamic “comments” about constraints.

Style, Naming, and Over-Commenting

  • “Self-documenting code” is widely discussed:
    • Good names help, but can’t encode multi-axis tradeoffs; extremely long identifiers are derided.
    • Some advocate brief names plus richer docstrings/comments, not encoding essays into function names.
  • Over-commenting and mandatory docblocks that restate the obvious are seen as noise that trains people to ignore comments.
  • Many prefer: comment public APIs and non-obvious internals; avoid boilerplate “what” comments.

Process and Culture

  • Several criticize dogmatic “no comments” and “Clean Code” purism; call for pragmatic, context-sensitive practices.
  • A recurring theme: comments, tests, names, and docs each cover different needs; mature teams balance all rather than absolutizing any one.