Gentoo Resisting?

Sure, bad things are bad.

But all else being equal, code that's properly documented is - as a general rule - more useful, and likely to be less buggy. Plus it often makes it easier to understand why some code is buggy (which all code inevitably is).

My experience has been that the kind of person who thinks that their code is so good that it doesn't need to be documented is - once again, as a general rule - the same kind of person that writes incomprehensible bug-ridden spaghetti.

But the difference between having no/little documentation and extensive documentation is even wider in cases like this, where the documentation describes glue layer interfaces and behaviour. I'm reasonably confident in asserting that it is an objective fact that documented APIs and protocols tend to be better than undocumented ones.

Overall, I don't think anyone can seriously claim that there's not even a correlation between the amount of documentation of some code, and its quality, unless they have some extraordinary evidence to support that claim. Not that they are *equal*, but *correlated*. Having tonnes of documentation is certainly not a guarantee of good code, but looking at the documentation *is* an extremely strong indication. I'm honestly surprised that anyone's even disputing this.