The article is great, though a more accurate (but admittedly less thrilling) title would have been "Poorly Documented Source Code Is Virtually Worthless".
Good source code includes level of intent comments, it explains the reasoning behind decisions (especially the tradeoffs that were made) and warns future readers of potential pitfalls.
In both a professional setting as well as when wanting to contribute to a favorite OSS project, few things are more frustrating than jumping into the code only to realize it's missing this type of info.
> "Poorly Documented Source Code Is Virtually Worthless".
And richly documented code is non-virtually worthless.
If you don't believe me, try parsing one of these so-called "literate
programs." Any 10-year vet will far more quickly grok a piece of code when
its textual flow isn't disrupted by verbiage that only makes sense to its
author.
Good source code includes level of intent comments, it explains the reasoning behind decisions (especially the tradeoffs that were made) and warns future readers of potential pitfalls.
In both a professional setting as well as when wanting to contribute to a favorite OSS project, few things are more frustrating than jumping into the code only to realize it's missing this type of info.