I used to own an API service at work, where we worked hard to ensure that the documentation was of a very high quality. When I got promoted and moved to a new team, I'd warned my manager NOT to hand it over to one team that was remarkably bad at their work. My manager did anyway.<p>During the transition, the new development lead said "I'm not going to read the documentation. If the code isn't self-documenting, we're going to rewrite it." Note that he said that not knowing anything about the service they were taking over. Also, it was in a language that had never established strong patterns for itself, so self-documenting when there are no strong patterns is generally meaningless.<p>Over the next 6 months, he proceeded to ruin the service to the point where it was impacting customers, and got fired for it. In any project of large enough size, self-documenting code falls apart unless you are <i>remarkably</i> good at it. IMO, Go's standard library is an exception to my experience.