[skyzyx]

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.

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.

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 remarkably good at it. IMO, Go's standard library is an exception to my experience.