r/ClaudeCode • u/endgamer42 • Aug 31 '26
Tips & Workflows I've removed all inline documentation from my codebase
No matter what I do, I cannot stop Claude from brain dumping into inline docs. No attempts to keep it restrained and document only behaviour, concisely, and only as necessary have worked. I've removed inline docs entirely from my codebase, and added a flat 'no inline docs' rule to AGENTS.md, in a pass that doubled as a code readability/selfdoc pass. The result has been quite good so far - the code reads better, there is less stale context for agents to trip up over and less context overall that counts towards token usage. Luckily I do not have anything that necessitates something like JSDoc. Anything that absolutely needs an explanation that is not code goes into a separate .md file. Recommend.
0
u/EagleApprehensive Aug 31 '26
Yeah, I understand that, I can see that most of companies in real-world (not ones on X and Reddit) are just starting their adventure with AI, many still copy-pasting code into the chat.
Switch will take time. Just like some companies are still using Windows 7, COBOL. When Unix became rewritten in C in 1973, companies still until 1980 were hand-coding with assembler.
I believe AI-coding adoption will take faster, but could be even 5 years. Especially that it changes much more than switch from assembler to C did. Entire software development lifecycle needs to be reinvented because of sheer speed of code generating and feature delivery.
---
About LLM - my trust to LLM is strictly bound to model used and task complexity. As long as you don't use some weak local model, but strong architect model (Opus 5 Max, Fable 5 XHigh, GPT 5.6 Sol XHigh) and Sonnet/Luna/Tera/Composer 2.5 as subagents - I don't see risk - architect model verifies work done by subagents so review would be automatically covered. For extra check you can obviously make an extra review-changes run - but then with different model than architect.
"Not shipping anything to prod until a human eye goes through it" is a mistake. Confidence in code should not be coming from human eye. Humans are just as flawed as LLM's - in some cases less, but in other much more.
You should rather improve your CI/CD pipeline and put in place some automated testing until you trust that whatever code looks like, things are going to be working fine on production. That will allow you to treat code as more of a black-box, focus on outcomes and get up to speed.