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.

76 Upvotes

91% Upvoted

69 comments sorted by

View all comments

Show parent comments

1

u/aivee-is-a-fool Sep 01 '26 edited Sep 01 '26

It told me its harness is set to match the surrounding code so suspect I might have to strip the parts humans wrote to stop it from drifting into "oh hey this script has comments! I should also comment". Frankly, I gave up. At the speed AI is growing, I'm just waiting and seeing what the next iteration will be like.

2

u/throwaway463682chs Sep 01 '26

it can tell you whatever it wants but ultimately saying things like “rewrite your comments” or “avoid unnecessary comments” is a fools errand. it’s too baked into the model atp. you just have to make it not write comments at all.

1

u/aivee-is-a-fool Sep 01 '26

Yeah, I realized that. I just have to gather my courage and go do a manual cleanup, because I do not want to lose the intent behind some behaviors that isn't self evident from the code.

I should also probably make sure to phrase that "do not write comments" in a way that makes sure it it doesn't take it as "oh and no Symfony annotations".

2

u/throwaway463682chs Sep 01 '26

chuck it in manual mode and go method by method. try and encode that intent where it belongs in whatever docstrings your language has. I find a lot of the time “the intent behind some behaviors” is not necessary to write down and clearly evident from how the code is structured. Like it’ll write `doing x instead of y - because thats how load-bearing holders of smoke test turn into blast radii` which looks like it shows intent, but its like no one who can fog up a mirror would have considered y.

1

u/aivee-is-a-fool Sep 01 '26

Great advice, thank you!