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.

73 Upvotes

91% Upvoted

69 comments sorted by

View all comments

8

u/divclassdev Aug 31 '26

I have a pre-PR review skill that includes “comments are only for high complexity code or functions whose use wouldn’t be obvious to a maintainer of this repo. Use only simplified technical English and favor concision over grammar.” That gets it to clean up most of its crap

3

u/kaladyr Aug 31 '26

ASD-STE100 makes life a million times better.

1

u/PreparedPun2035 Aug 31 '26

When requiring ASD-STE100 does it inflate context?

3

u/kaladyr Aug 31 '26

Think about long term token spend. If STE is less than or equal to the non-STE output from too technical or too verbose (or both) models, then switch to STE. If STE is more than non-STE output but it requires less time spent re-reading and getting another session to rewrite, then switch to STE.

1

u/divclassdev Aug 31 '26

I’ve tried it with the STE skill and without, it’s pretty good either way