This is dead on. Similarly, please document the "why not". As in, "here's some code that implements what should be an easy idea in an unexpected why. Why didn't

This is dead on. Similarly, please document the "why not". As in, "here's some code that implements what should be an easy idea in an unexpected why. Why didn't I did it it normal way? Because this one special business case would break, and our customer got mad and threatened to cancel."