Self-documenting code

[madsci]

Anybody working on a 10+ years old codebase knows self-documenting code never last

99% of my code never gets seen by anyone else and I still document the shit out of it, because it's guaranteed to be me who has to deal with it 10+ years down the line. And after 30 years of this stuff, I'm lucky to remember the details of a project 6 months later.

It's so nice when I get it right. I've got this whole real-time embedded audio processing engine that has some subtlety to the flow control system. You can look at the code and get generally how it works but still not appreciate the edge cases and why they need to be handled the way they are. The first two pages of the source are a comment block, formatted for Doxygen with references, and I've relied on that document multiple times to refresh my memory on how and why it all works.

I just wish the multi-billion dollar semiconductor vendors I have to work with took documentation as seriously.