Your point about documentation makes me think of a similar point. We often debate whether documentation is good or bad. Overreliance on any documentation is, I would agree, something to be avoided. That said, the best kind of documentation is that which an engineer would seek out in order to gain a better understanding of some piece of functionality. Sometimes a chunk of code is simply too complex to be comprehensible, and so associating a clear comment alongside the code is helpful. By contrast, the sort of documentation that someone leaves to cover for their poorly designed API— and that no other engineer would have any inkling that they needed to seek out in the first place—is the worst sort of documentation. It really only serves to allow the engineer to say, “didn’t you read the comments?” when they are called out on their crappy design.

In fact, I can recall many times where I’d seen an engineer kicking themselves when they “misused” and API and realized that they hadn’t read the comment that explained the API’s secret ingredient. In those cases, I always tried to assure the engineer that they were not the ones who ought to be kicking themselves.