Knowledge Vault

Code Comments

3 min read

Code Comments

Code comments are annotations within source code intended for human readers rather than compilers. The most important insight about comments is that they are a failure to express intent in code itself — when you need a comment to explain what code does, consider whether a rename or refactoring would eliminate the need. However, comments are essential and valuable when they explain why something is done, not what or how.

The test for a comment’s worth is whether it adds information that cannot be inferred from the code. A comment that merely restates the function signature or repeats what the expression obviously computes is noise — it clutters the file, ages poorly, and trains readers to ignore comments, which means they’ll also ignore the ones that matter.

Good vs. Bad Comments

Good Comments

Intent comments explain decisions that would otherwise appear arbitrary:

// Using insertion sort here: input arrays are almost always < 10 elements,
// where insertion sort's cache locality outperforms quicksort.
function sortItems(items: Item[]): Item[] { ... }

Warning comments flag non-obvious hazards:

// Do not parallelize this section — the external API rate-limits to 1 req/sec
// and returns silent 429s that appear as successful responses.
for (const batch of batches) { ... }

TODO comments track known debt with context:

// TODO: Remove this fallback after the migration deadline (2026-06-01).
// Linear: PROJ-442

Clarification comments for unavoidably obscure code (regular expressions, bitwise operations, legal constraints):

// Matches ISO 8601 datetime with optional fractional seconds and timezone.
const ISO_DATETIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;

Bad Comments

Redundant comments restate what the code already says:

// Increment the counter
count++;

Misleading comments describe behavior that no longer matches the code — often caused by updating logic without updating the comment. Stale comments are worse than no comments.

Commented-out code left in the codebase without explanation. Use version control — if code might be needed later, a commit message is the right place to preserve it.

Journal comments recording change history in the file itself. Version control does this better.

Documentation Comments (API Docs)

Public APIs benefit from structured documentation comments (JSDoc, docstrings, Rustdoc). These differ from inline comments in purpose — they document the contract for callers who may never read the implementation. Cover: parameters, return values, thrown exceptions, preconditions, and side effects. Do not document the obvious.

Key Concepts

  • Comments explain why, not what — the code itself should express what
  • Stale comments actively mislead; treat comment maintenance as part of the change
  • A comment you feel compelled to write often reveals a refactoring opportunity
  • Public API documentation comments serve callers and are worth investing in
  • Commented-out code should be deleted, not preserved
  • Meaningful Names — good names eliminate the need for explanatory comments
  • Small Functions — well-named small functions are self-documenting
  • Code Reviews — reviews catch stale or misleading comments before they cause damage

References

  • Martin, R. C. (2008). Clean Code: A Handbook of Agile Software Craftsmanship. Chapter 4: Comments.
  • Boswell, D., & Foucher, T. (2011). The Art of Readable Code. O’Reilly.

Graph View

Backlinks