Documentation is like sex. If it is good, it is good. If it is bad it is good
-Assholes who don't know what it is like to work with mature code bases.
"Our code is self-documenting. If you need documentation then the code isn't written well enough"
-Assholes who don't know what it is like to work with mature code bases.
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.
Management thinks he’s brilliant. Everybody else thinks he’s an insane asshole.
Just because you know people who can say this with sincerity and gravitas doesn’t mean there aren’t assholes.
There are always assholes.
"Our code is self-documenting. If you need documentation then the code isn't written well enough"
-Assholes who don't know what it is like to work with mature code bases.
- People who don't know how to write clean code
1) Why (requirements, decision points)
2) What (use cases, interactions, external APIs)
3) How (internal APIs)
4) Who (SMEs, owners, servers)
And don't waste people's time; don't document things that are obvious.
If it is good, it's great. If it is bad, it is better than nothing.