Inline Documentation

Documentation remedies ambiguity and supplies missing context. Good code is self-documenting — it shows the what, so a comment must earn its place by adding the why. Keep docs lean.

What to document

• Comment where the code surprises: intent, constraints, workarounds, logic that looks wrong but works. Add the why when it spares the reader a wrong guess; let plain code speak for itself.
• Reserve inline comments for genuinely complicated logic; short phrases.
• Mark unfinished work with TODO/FIXME.
• Keep a comment beside its code and revise both in one edit; comments rot as code drifts.
• Write for the future reader, who knows the code but not your session or the surrounding stack: keep comments timeless and self-contained.

How to write it

• Use block doc comments (JavaDoc, JSDoc, docstrings) for the standard, dev-readable format.
• Write like a senior developer: terse fragments, human names, specific over generic.
• Every comment is signal: cut the noise (keeps, so, because, stays), and prefer commas and semicolons to full sentences.
• Shun ceremony: structure speaks for itself, so section headers like // -------- Variables -------- only bloat tokens.
• Use typeable ASCII only; it keeps docs easy to edit.