The Code as Documentation crowd produce beautiful code, and I follow much of the practice, but while it is good at self-documenting what is happening, it's hard

The Code as Documentation crowd produce beautiful code, and I follow much of the practice, but while it is good at self-documenting what is happening, it's hard to get the why entirely into code without being obtuse. Especially when working around framework limitations. This becomes very important in the maintenance phase. I can see you getProductCollection, I know what that does, but why do you do nothing with it? Oh it's because it needs to be loaded before presenting the cart, and there's a bug in the framework that fails to do so in this scenario. Also business requirements can be reaaally asinine, a makeThisParticularButtonGreenSeeMeetingNotes20122023() would be pretty lame but that is often required information for a developer revisiting a feature and wondering if something was a bug or intended.