alt Hacker NewsSeeing more and more projects eschew code docs with the idea that "well architected code can be queried by LLMs" and stick to more functional runbook style docs. It really is unlikely that at any given point all of the docs of a project are up to date with the code.
I'm generally aligned with this, but it is predicated on the whole "well architected" code part.
I'd rather see unit tests as documentation.
The test can show intended use, show interesting corner cases, and I know it is up to date because it is constantly running and passing.
I think that is a huge underrated benefit of adding a lot more testing.
If I think a developer is going to ask a question of how something works, or about a corner case, isn't that deserving of a test, so they can just see proof of the answer to their question immediately rather than trying to re-derive it?