4 ms·

I think a pragmatic compromise here is to do "chatty" programming. Don't tell me tautological comments("add X and Y"), but I want to know what the overall stra

by mhh__ 5y ago

I think a pragmatic compromise here is to do "chatty" programming. Don't tell me tautological comments("add X and Y"), but I want to know what the overall strategy of your algorithm is. Is it flawed? Do you like it? What needs improving? Why did you choose this data structure over that one? It doesn't have to be much detail, but having a chunk of text to read is some of the best onboarding you can get for a new piece of code. Code with comments that simply write down what it is supposed to do, is not documented properly. I can now see what it does in a documentation generator, yes, but the moment I need to work on that code it's just an opaque piece of crap.

akkartik 5y ago
Why compromise?! I never said LP is bad. I just said we can do it better than Knuth does it. Knuth didn't take us to the promised land, but he did show us a path to it.
- mhh__ 5y ago
  The compromise is between using full fat literate programming, and keeping your job (i.e. using it at scale)
  - akkartik 5y ago
    Ah right :) I thought perhaps you were alluding to something I said.
BenFrantzDale 5y ago
Yeah, explaining “what” in comments is rarely helpful. For professionals, a certain degree of language-literacy should be assumed: `#include <string>` doesn’t need a comment about its semantics; it only wants a comment if it’s surprising that the containing file would need it. Here are two examples in the past week I’ve suggested changes on a PR to remove comments: 0. `case foo: // fallthrough` -> `case foo: [[fallthrough]];`. That won’t rot and doesn’t make the reader switch languages while reading. 1. `if (code < 1000) { // http codes are less than 1000` -> `constexpr auto maxHttpCode = 999; if (code <= maxHttpCode) {`. I find that even if it’s a local constant, having it named is the first step toward reuse. My favorite: `void setTimeout(int time); // in milliseconds` -> `void setTimeout(std::chrono::milliseconds time);` which adds unit-safety and eschews comments that can rot.

by mhh__ 5y ago

akkartik 5y ago

Why compromise?! I never said LP is bad. I just said we can do it better than Knuth does it. Knuth didn't take us to the promised land, but he did show us a path to it.

mhh__ 5y ago
The compromise is between using full fat literate programming, and keeping your job (i.e. using it at scale)
- akkartik 5y ago
  Ah right :) I thought perhaps you were alluding to something I said.

BenFrantzDale 5y ago

Yeah, explaining “what” in comments is rarely helpful. For professionals, a certain degree of language-literacy should be assumed: `#include <string>` doesn’t need a comment about its semantics; it only wants a comment if it’s surprising that the containing file would need it. Here are two examples in the past week I’ve suggested changes on a PR to remove comments: 0. `case foo: // fallthrough` -> `case foo: [[fallthrough]];`. That won’t rot and doesn’t make the reader switch languages while reading. 1. `if (code < 1000) { // http codes are less than 1000` -> `constexpr auto maxHttpCode = 999; if (code <= maxHttpCode) {`. I find that even if it’s a local constant, having it named is the first step toward reuse. My favorite: `void setTimeout(int time); // in milliseconds` -> `void setTimeout(std::chrono::milliseconds time);` which adds unit-safety and eschews comments that can rot.