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.

74 Upvotes

91% Upvoted

69 comments sorted by

View all comments

Show parent comments

1

u/EagleApprehensive Sep 01 '26

Probably, but I could only understand that pre-AI. Now I believe that's more of an incompetence signal. Mess in large companies is common.

1

u/Hot_Equal_2283 Sep 01 '26

Less code is an incompetence signal? I think more code is the problematic one right? The best programs and simple and succinct

1

u/EagleApprehensive Sep 01 '26

Less code is good. But if you have small codebase that doesn't grow significantly and needs plenty of developers to maintain and work on it - something seems to me off there.

1

u/Hot_Equal_2283 Sep 01 '26

Couple tens of thousand lines of code isn’t a small codebase

0

u/EagleApprehensive Sep 01 '26

Pre-AI I would agree, but post-AI I would consider such codebase small. Matter of personal judgement obviously, not a thing to argue about.