[EliRivers]

I'd also have to document why certain decisions were taken.

Yes please. So much this. With evidence, please, so that the decisions can be revisited in the future and changed when they no longer apply. Every day I open another source file on a system that was built over a decade by a rotating cast of mostly first job software engineers without adequate mentorship and (I wish I was making this up) having their C++ code reviewed by a C programmer who gave them comments such as "just turn all these functions into one-line macros", and someone who appeared to be mainlining late-nineties OOP hype like it was going out of fashion and needed to get it all on the page before someone beat him to death with an old Vic 20.

Every day we stare at it and ask ourselves why. Why was it done like this? Was there a good reason back then? Does that reason still exist? If I rewrite it to remove all this horror, will something else break? Even, oh God, even "What is this actually meant to do?" I can see what it does do. What it does do makes no sense. Did it ever make sense?

Even the occasional comment like "cheeky hack for performance" is often more hindrance than help when a quick test shows it actually makes performance worse. Did it ever improve things? Did the hardware change underneath it such that it no longer helps? Did other code change such that it no longer applies?

Anyway, where this was going is that a decision recorded without evidence or even the factors considered might as well have been a coin toss to the software archaeologist having to maintain it in a decade's time. If the decisions and reasoning aren't recorded, you're forcing someone to attempt to reverse-engineer your state of mind, and that's an expensive and impossible job.