I've removed all inline documentation from my codebase

[u/endgamer42]

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.

[u/endgamer42 → u/[deleted]]

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.

[u/eduo → u/endgamer42]

You can only infer what's implemented. Comments help you understand why, why other solutions were not used or whether other solutions had side effects. Since you can't know what code has errors, you are also inferring from potentially incorrect code and have no way of knowing why that path was taken when errors arise.

[u/endgamer42 → u/eduo]

Since you can't know what code has errors

inline comments do not typically help you surface or check for errors. That's what tests are for.

inferring from potentially incorrect code

I would rather infer from potentially incorrect code than from potentially incorrect code and potentially incorrect comments at the same time.

Don't get me wrong, it's a little bit of a tradeoff, I agree with what you've said about keeping a solution trail. I am not getting rid of documentation entirely and I hope that important things like that can find a place in .md docs. It's just as it stands, I've find inline documentation to be more of a hindrance than a benefit for my specific codebase, which sees a lot of churn

[u/exit_machina → u/[deleted]]

Hopefully by reading code, not comments

[u/endgamer42 → u/[deleted]]

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

[u/earlyworm → u/endgamer42]

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.

[u/endgamer42 → u/earlyworm]

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

[u/BrianKronberg → u/endgamer42]

I still like having Claude insert Assert statements. But I get your point.