Why Not Comments

Original Article ↗ Hacker News Discussion ↗

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.