Forcing AI to document code that only AI will ever touch is dumb
retained text
the whole argument for comments is "future you won't remember this." sure. but future you also has an AI assistant that can read the actual code and explain it accurately in seconds. no maintenance required. never goes stale. because here's the thing, comments do go stale. code doesn't lie, comments do. that function that "// returns users sorted by date" hasn't done that since march. now it's not documentation, it's a trap. and if your code genuinely needs a comment to be understood, the comment isn't the fix. the code is the problem. bad naming plus a comment is still bad code. good naming needs nothing. the only comment worth writing is the WHY behind something that looks wrong but isn't. a weird workaround, a non-obvious constraint, a "don't touch this or X breaks." one line. that's it. everything else is just habit dressed up as discipline. AI literally understands code better than english. code is exact and unambiguous. your comment is vibes. so you're translating from precise to vague so AI can translate it back. pointless round trip. we document because senior devs told us to, who were told by their senior devs, before any of us had tools that could read the code itself. tldr: good code explains itself. AI explains the rest. stale comments actively mislead. the habit has outlived the reason.
document fetched 2026-09-03 00:41 · canonical https://reddit.com/r/ClaudeCode/comments/1w5cf2l/forcing_ai_to_document_code_that_only_ai_will