3 ms·

By "prose" here I guess you mean comments? Strongly disagree. Most code should be self-documenting through variables, well organized functions, etc. Public APIs

By "prose" here I guess you mean comments? Strongly disagree. Most code should be self-documenting through variables, well organized functions, etc. Public APIs should contain lots of documentation, but the actual implementation code should be sparsely commented. Otherwise you now have two "code bases" to maintain.

oneeyedpigeon 9y ago
> By "prose" here I guess you mean comments? That's a big assumption. I assume the OP meant not quite literally 'prose' but 'good, clear writing' which can certainly be achieved using the built-in keywords of a language combined with well-chosen identifiers.
chrismorgan 9y ago
Public API documentation is very definitely a part of what I was meaning; but most code can also benefit from liberal explanation of how and why certain things are as they are. Many comments that are written could be better handled by restructuring the code they reside in the midst of, but many code comments can’t be done otherwise, and to attempt to do otherwise would be convoluted. To take an example of some code I wrote today: // Object.values is from ES2017 and Overture uses it; anything that has it will // have the other things from ES6 that we need, so we don’t need to add the // weight and load time of core-js for them. Browsers that thus need core-js // are approximately: IE, Safari≤10.0, iOS≤10.2, Chrome≤53, Firefox≤46, // Edge≤13?. No up-to-date browser needs it (for better or for worse). if ( !Object.values ) { 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/lib/libumem/common/umem.c 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_borrowck/borrowck 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.
- coldpie 9y ago
  Sure, of course it's needed sometimes. But I was disagreeing with this statement: > And good code will contain a lot of prose. I disagree. Good code can also contain no comments. It's not an either/or thing.
  - chrismorgan 9y ago
    I will adjust my position to this: non-trivial good code will contain a lot of prose.

oneeyedpigeon 9y ago

> By "prose" here I guess you mean comments? That's a big assumption. I assume the OP meant not quite literally 'prose' but 'good, clear writing' which can certainly be achieved using the built-in keywords of a language combined with well-chosen identifiers.

chrismorgan 9y ago

Public API documentation is very definitely a part of what I was meaning; but most code can also benefit from liberal explanation of how and why certain things are as they are. Many comments that are written could be better handled by restructuring the code they reside in the midst of, but many code comments can’t be done otherwise, and to attempt to do otherwise would be convoluted. To take an example of some code I wrote today: // Object.values is from ES2017 and Overture uses it; anything that has it will // have the other things from ES6 that we need, so we don’t need to add the // weight and load time of core-js for them. Browsers that thus need core-js // are approximately: IE, Safari≤10.0, iOS≤10.2, Chrome≤53, Firefox≤46, // Edge≤13?. No up-to-date browser needs it (for better or for worse). if ( !Object.values ) { 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/lib/libumem/common/umem.c 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_borrowck/borrowck 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.

coldpie 9y ago
Sure, of course it's needed sometimes. But I was disagreeing with this statement: > And good code will contain a lot of prose. I disagree. Good code can also contain no comments. It's not an either/or thing.
- chrismorgan 9y ago
  I will adjust my position to this: non-trivial good code will contain a lot of prose.