Code Comments

Write documentation that lives with the code it describes. Plain language. No jargon. Explain the why, not the what.

Core Philosophy

Co-location wins. Documentation in separate files drifts out of sync. Comments next to code stay accurate because they're updated together.

Write for three audiences:

1. Future you, six months from now
2. Teammates reading unfamiliar code
3. AI assistants (Claude, Copilot) who see one file at a time

The "why" test: Before writing a comment, ask: "Does this explain why this code exists or why it works this way?" If it only restates what the code does, skip it.

Documentation Levels

File Headers