Code Comments

Guidelines for writing effective comments that explain intent without cluttering code.

When to Use

• Adding comments to explain non-obvious code
• Reviewing existing comments for clarity and accuracy
• Deciding whether code needs a comment or should be refactored instead

NOT for: language-specific documentation syntax (JSDoc, docstrings, Go doc comments), documentation generation, or commit messages.

Procedure

1. Determine if a comment is needed — code should be self-documenting when possible. A comment is warranted when:
   • The why is not obvious from the code
   • A non-obvious decision or constraint exists
   • An edge case or workaround needs explanation
   • Future work or known limitations should be flagged (TODO/FIXME)