Matt Gerrans writes regarding poorly documented code being the industry standard:

The GTSL [Grep the Source, Luke!] argument is that the code is the documentation. Unfortunately, the code is not the truth. It is full of lies, deceit and broken promises. Looking at the code, it is quite easy to follow the wrong path.

He writes that this doesn’t come as a surprise, since code examples in programming books never are well commented, since good commenting isn’t taught in schools, and since there aren’t any books on the subject. “Even books that talk about programming style,” he continues, “often let you off the hook by saying that even more important the code should have meaningful variable and method names than thorough comments.”

Should we really accept swinish code and make up for it by learning to comment it better? If we see programming as a form of technical writing, the comments would be the footnotes. Getting really good at writing footnotes, and writing lots of them, doesn’t produce great books. Actually, for books it’s the other way around: the writer can get away with incomprehensible footnotes, or footnotes that doesn’t address the average reader. For instance, in Linked by Albert-László Barabási, the footnotes largely contain mathematical formulas.

I’m not saying that code comments are useless, but it is possible to write readable code. And as it is the code that matters, it’s far more important to teach good code writing style.