Inline comments vs commit messages: what goes where

Code comments explain what and why at the point in the code. Commit messages explain why a change was made at a point in time. Both are important, and they serve different purposes — confusing the two leads to neither being useful.

A well-formed commit message follows this structure:

feat(auth): add refresh token rotation

Refresh tokens were single-use, which caused session drops
when concurrent requests both tried to use the same token.

Now each use of a refresh token issues a new one and
invalidates the old. This adds a 1ms overhead per auth
call, acceptable per the API SLA.

Closes #482

The first line is the subject: type, scope, and a brief description. Keep it under 72 characters. The body explains the why — what problem existed, what decision was made, what the tradeoffs are. The footer links to tickets.

Conventional commit types:

feat     — new feature
fix      — bug fix
refactor — restructuring without behavior change
docs     — documentation only
test     — tests added or changed
chore    — build, deps, tooling

When you run git blame on a confusing line of code and the commit says "fix stuff," you've lost the context forever. When it says "fix(payments): handle negative amounts in EUR due to refund ledger inversion" you've found your answer without digging through Slack history.

Inline comments and commit messages are complementary. Inline comments are for permanent, always-visible context. Commit messages are for historical context about why something changed.