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 d…