auto-comments

Code commenting best practices during review enforce a value hierarchy where comments reveal unseen intent or risk rather than narrating obvious code. You apply litmus rules to prune noisy comments, tighten context, and ensure high-value documentation across languages.

Writing purposeful code comments requires applying a value hierarchy that prioritizes 'why not', 'why', and 'beware' notes over 'what' or 'how' descriptions. You avoid anti-patterns like restating function names or narrating control flow to capture genuine reasoning and risk.

When refactoring code, add comments to capture behavioral intent, anti-pattern avoidance, and hidden risks, and remove comments that merely narrate the obvious or restate code structure. Litmus rules determine whether a comment adds unseen value or creates noise.

This commenting approach works across all programming languages by applying universal litmus rules and a comment-value hierarchy to guide when to add, prune, or tighten documentation. It handles language-agnostic formats like docstrings, JSDoc, and RustDoc identically.

Common code commenting anti-patterns to avoid include narrating the code, restating the function name, and commenting control flow. These noisy patterns fail the value litmus test because they restate the obvious instead of revealing underlying context, reasoning, or risk.

Documenting 'why not' reasoning involves writing comments at the top of the value hierarchy to capture why specific approaches or anti-patterns were avoided. This ensures future developers understand the hidden risks and behavioral intent behind the chosen implementation path.