The debate is old. Where does context live — in the code, in a wiki, in a README, in a commit message? Every team has a different answer. I've always had comments in my code (sometimes too much), but better than nothing. Now I'm more sure than ever.
── SWIFT ──// Phase 1 — Agile: comment the code ✓ // Phase 2 — Corporate: wiki page (last edited 2019) // Phase 3 — Confluence: page nobody reads // Phase 4 — Pull request: description nobody clicks // Phase 5 — README.md: getting warmer... // Phase 6 — .md in repo: closer, but still a separate file // Phase 7 — Back to §1: comment the code ✦
“Closest to the source of truth wins.”
A comment sitting right next to the function it describes can't drift the way a wiki page can. It moves with the code when files are renamed. It gets deleted when the code gets deleted. It ages in sync.
AI Makes This Non-Negotiable
When AI touches your code — fixing a bug, extending a feature, refactoring a file — it reads that file. It reads the function. It reads the comment right there at the decision point. No extra step. No separate file to fetch. No mental mapping from documentation back to code.
If the comment explains why, not just what, the AI has everything it needs. "Single commit point — everything in memory until this is called at step 4." One line. AI reads it before touching that function and immediately understands the constraint.
With tools like SonarQube checking code quality, and AI doing the bulk of implementation, keeping comments accurate becomes easier too — the AI that wrote the code can update the comment. The feedback loop is tight.
I asked Claude directly. Here's what it said:
The Rule
The AI's answer is the right one. There's a clean division:
- ✦Specific function or decision → comment in the code, at that line
- ✦Cross-cutting constraint that spans multiple files → .md or memory entry
- ✦Architecture overview → wiki (always-on, always loaded — like CLAUDE.md at org scale)
- ✦Everything else → probably doesn't need documenting at all
This also helps with token efficiency. When AI reads a file for a change, inline comments load automatically as part of that context. Pointing AI at a separate wiki or .md file costs extra tokens and an extra step. The comment is already there.
“Ask AI yourself — or save the tokens. In more ways than one. — Walter Mak”