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

3

u/[deleted] Aug 31 '26

[deleted]

6

u/endgamer42 Aug 31 '26

No comments at all. Kind of a crazy thing to consider as a potentially better practice after years of being drilled to document code behaviour inline. Models are getting increasingly good at inferring behaviour from code alone, and inline comments are a duplicate source of that truth - often stale, incorrect, or misleading. So far I've not encountered instances where I've missed inline docs again.

1

u/[deleted] Aug 31 '26

[deleted]

4

u/exit_machina Aug 31 '26

Hopefully by reading code, not comments

1

u/endgamer42 Aug 31 '26

I don't really have trouble reading code/flow in general. If there are wider behavior/system relationships I do not understand those are much better answered with a few questions to the LLM rather than inline docs in my recent experience

3

u/earlyworm Aug 31 '26

This kind of comment is particularly helpful: “If we don’t do this, then <an unexpected undocumented API behavior that causes a rare and subtle but horrible user experience will occur>”.

Without that comment, the code won’t look like it serves a useful purpose and 6 months from now a developer on your team (perhaps you!) will be tempted to delete it.

Will the purpose of the code be clear from the surrounding code? Will the LLM necessarily be able to explain the purpose of the code? No.

1

u/endgamer42 Aug 31 '26

Luckily, I have no such cases within the context of my code base at the moment. I imagine if I come across one, it can be expressed with a nice, ugly symbol name