Earlier quoted context omitted.
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
Are there any good systems that somehow enforce consistency between documentation and code? Maybe the problem is fundamentally ill-posed.
Programming languages can't understand semantics, and that's why we program in the first place. I can't tell a computer "I would like a program to achieve this goal", instead I have to instruct it how to achieve the goal. Then, I would need to document elsewhere what the goal is and why I'm doing it.
LLMs change that, we can now legitimately ask the model "I would like a program for this goal". But the documentation is lost in the code if we don't save comments or save the prompt.
Git commits are also a good source of documentation. They shouldn't describe what we're doing, because I can just read the code. But often, I come across code and I'm thinking "why are we doing this? Can I change this? If I change it, what are the side effects?" If I'm lucky, the git blame will answer those questions for me.