Self-Documenting Code

A comment explaining what code does is a failed refactor. Comments rot — no compiler, test, or linter checks them, so they drift from the code and eventually lie; code cannot lie. Replace the comment with the construct it was compensating for:

• Named constants for magic values:

  if (status == 5) { ... }        // 5 means the message was sent
  if (status == MESSAGE_SENT) { ... }   // comment now redundant — delete it
  

• Named intermediates and operations, so the code reads as the comment would have:

  const userIsAuthor = message.authorId === user.id;
  const editWindowOpen = message.ageMinutes() < EDIT_WINDOW_MINUTES;
  if (userIsAuthor && editWindowOpen) { ... }
  

  Inline a one-use expression when a local name would merely restate its syntax. Keep a named local when it names a domain concept, records a snapshot, avoids repeated evaluation, or makes dense code easier to read. Extract a function only when it recurs, represents an independently meaningful domain operation or boundary, or lets a still-complex caller read as coherent happy-path steps. Length is not the test: a short helper earns its place when its trustworthy name tells the caller everything needed at that level of abstraction. If the reader must open it to discover behavior relevant to the caller, its name or the extraction is wrong. Never extract solely for isolated testing.
• Types that encode the contract: unique_ptr instead of "// caller must free"; Optional<Timestamp> instead of "// -1 means not set"; Duration instead of "// in seconds". The compiler enforces types; nobody enforces comments.

Legitimate comments say why, which code cannot express: performance-motivated weirdness ("unrolled — profiler showed this loop is 40% of frame time"), links to the algorithm, paper, spec, or ticket the code implements, warnings about non-obvious hazards.