illumos-gate

dependencies.O = [ 'core-js' ]; } This comment is about explaining why a thing is as it is. Self-documentation by naming tends to only take you as far as what; for a case like this, it would have led to something like this: var needCoreJs = !Object.values; if ( needCoreJs ) { dependencies.O = [ 'core-js' ]; } This wouldn’t have explained why core-js is needed—or why I considered Object.values a suitable test. I tend to draw a distinction between single-line comments which are only sentence fragments, and prose. Prose is beautiful in code. A part of the illumos codebase was linked to elsewhere in these comments, and I think it satisfies my point also: https://github.com/illumos/illumos-gate/blob/master/usr/src/.... 600 lines of documentation up front is more than I’d typically expect, but it’s well done in this case. After that, there’s liberal application of explanatory comments where they can help. The rustc borrow checker is another example that I like: https://github.com/rust-lang/rust/tree/master/src/librustc_b.... What is now README.md used to be somewhat shorter (though still long and involved!) and in mod.rs. Look at both files. The documentation here is all about implementation detail; without this extensive prose, I’d say: good luck understanding borrowck. With it, it’s involved, but quite attainable, and you can approach the code without needing excessively deep and intricate understanding of everything about rustc. Comments can be done badly, but they can also be done really well.

es.