2 ms·

> Extremely high-performance database code is not what most of us are doing, however. That's true. But look at the overall coding style in that file: Code is

> Extremely high-performance database code is not what most of us are doing, however. That's true. But look at the overall coding style in that file: Code is structured into cohesive blocks, which are prefixed by a comment which explains in english language the intention, pitfalls, limitations of the following code. I find this quite elegant and readable. An ideal to aspire to. I am not advocating nonsensical JavaDoc: // Get's foo from bar private Foo get_foo(Bar bar); If you are able to just use names and types to document your intentions, pitfalls etc ... then by all means, do just this. E.g. for( person in address_book ) { body = template.render( name => person.name, ... ) mail = Mail.new(person.email, body) mailgun.queue(mail) } However, if stuff get's more nuanced don't be afraid to use english language to explain what you are doing. You future self will thank you : )

zmmmmm 7y ago
> If you are able to just use names and types to document your intentions, pitfalls etc ... then by all means, do just this That's sort of the point. Step 1, your code should be self explanatory. When the natural interpretation a reasonable person would have from reading the code differs from reality: that's when you add Step 2: add comments to "fix" the gap between perception and reality. The less Step 2 is necessary the better.
heinrichhartman 7y ago
> I would want that function to be multiple smaller functions with docstrings and such [...] I have tried that style in the past, and have reverted to writing longer functions with intermittent comments. I now consider "single caller functions" a smell. If logic is serial (do A, then B, then C) it's fine to have serial code: main() { ... A ... ... B ... ... C ... } The issue with splitting out the intermediate steps into functions is, that the serial flow is broken. Instead of the logic now looks something like A(...){ ... } C(...){ ... } main() { A(...) ... B ... C(...) } Where B might have been a tiny task, that is not worth splitting out. In effect: - The ordering of the logic is broken. - Passing arguments can be a pain, if a lot of pieces are touched. And what have you gained? Not sure there are many upsides besides debatable aesthetics of avoiding inline code comments.

zmmmmm 7y ago

> If you are able to just use names and types to document your intentions, pitfalls etc ... then by all means, do just this That's sort of the point. Step 1, your code should be self explanatory. When the natural interpretation a reasonable person would have from reading the code differs from reality: that's when you add Step 2: add comments to "fix" the gap between perception and reality. The less Step 2 is necessary the better.

heinrichhartman 7y ago

> I would want that function to be multiple smaller functions with docstrings and such [...] I have tried that style in the past, and have reverted to writing longer functions with intermittent comments. I now consider "single caller functions" a smell. If logic is serial (do A, then B, then C) it's fine to have serial code: main() { ... A ... ... B ... ... C ... } The issue with splitting out the intermediate steps into functions is, that the serial flow is broken. Instead of the logic now looks something like A(...){ ... } C(...){ ... } main() { A(...) ... B ... C(...) } Where B might have been a tiny task, that is not worth splitting out. In effect: - The ordering of the logic is broken. - Passing arguments can be a pain, if a lot of pieces are touched. And what have you gained? Not sure there are many upsides besides debatable aesthetics of avoiding inline code comments.