Sorry, parent poster: Gotta agree w/ above comment here. With the minor warning that the unit tests are included in this. In a good environment, I should be able to go to the tests to understand not only WHAT the code is doing but WHY it's doing it. No matter how 'mature' the code base is.
In any mature code, there is going to be unintuitive code that only exists to work around an external issue beyond your control.
Recent example: when you authenticate to OpenSSH running on macOS 10.13 or 10.14, make sure to never attempt keyboard-interactive auth after password auth, or the server will stop responding.
Somewhere you need to write this fact down, so that the next person who comes across your auth code doesn't change the order of authentication methods.
You need to document things like that.
If you have a mature code base, you'll have dozens, or hundreds of these workarounds for all kinds of issues. If you look at the code, it'll seem inefficient. If you don't document why the code looks like it does, then someone will come along (possibly you) a few years in the future and "optimise" that line.
Sure, you could have a unit test that checks whether the workaround is in place. But then you STILL need to document why that unit test is there, or someone will come and consider it pointless and remove it.
