Code cannot and should not be self documenting at scale. You cannot document "the why" with code. In my experience, that is only ever used as an excuse not to write actual documentation or use comments thoughtfully in the codebase by lazy developers.

▲

bdangubic 5 hours ago | parent [-]

this always starts out right but over the years the code changes and its documentation seldom does, even on the best of teams. the amount of code documentation that I have seen that is just plain wrong (it was right at some point) far outnumbers the amount of code documentation that was actually in-sync with the code. 30 years in the industry so large sample size. now I prefer no code documentation in general

▲

derrak 4 hours ago | parent [-]

Are there any good systems that somehow enforce consistency between documentation and code? Maybe the problem is fundamentally ill-posed.

	▲	jurgenburgen 6 minutes ago \| parent \| next [-]
		Ultimately the code is the documentation.
	▲	reverius42 22 minutes ago \| parent \| prev \| next [-]
		Keeping the documentation in the repo (Markdown files) and using an AI coding agent to update the code seems to work quite well for keeping documentation up to date (especially if you have an AGENTS.md/CLAUDE.md in the repo telling it to always make sure the documentation is up to date).
	▲	sgc an hour ago \| parent \| prev [-]
		I am not saying it doesn't matter because it does, but how much does it matter now since we can get documentation on the fly? I started working on something today I hadn't touched in a couple years. I asked for a summary of code structure, choices I made, why I made them, required inputs and expected outputs. Of course it wasn't perfect, but it was a very fast way to get back up to speed. Faster than picking through my old code to re-familiarize myself for sure.