expression-annotate

Guide adding meaningful comments that explain the "why" behind code using knowable information from names, history, tests, and context. Use when: (1) asked to refactor code where implementation changes might erase the reasoning behind current decisions, (2) code requires multiple readings to understand because the rationale behind its structure isn't captured anywhere, (3) reviewing code that lacks context and the distinction between intentional decisions and bugs is unclear, (4) encountering patterns that violate project conventions and the difference between technical debt and necessary deviation is ambiguous, (5) onboarding to a codebase reveals implicit knowledge that exists only in developers' heads, (6) code appears wrong or overly complex but git history or tests suggest deliberate choices, (7) committing code with non-obvious decisions that future readers will need explained, (8) pull request comments contain explanations that would be more valuable preserved in the code itself