I’ll agree, docstrings are better for documenting a function than just a comment.
However, the author seems to jump through hoops in the next example to break one function into four, just to avoid some single line comments. Unless those code blocks make sense as functions (they’re used/duplicated elsewhere), you’re just making work for yourself. Why not turn it into 12 functions? One for each line of code?
I’m reminded of the admonition that there are only two hard problems* in computer science – cache invalidation, and naming things. The more functions you have, the more things you have to name.
The rest of it – name your magic numbers, use tuple unpacking, comment “why” instead of “what” – is good practice. I’m just not a fan of making functions just to avoid writing a comment.
single use functions are fine; I often break 20+ line functions apart and it makes it easier to test and reason about, it’s not just to avoid comments: block comments are just a sign that the function might be getting too complex.
On the other hand, I often have wished that the author of the code I am reading had just kept their original 20 line function around instead of splitting it up into a zillion little functions that force me to constantly jump around to figure out what is actually going on.
it’s turtles all the way regardless; but it’s much easier to handle side effects if you have more numerous but smaller functions.
I prefer that because fully reading a module or component is not the most common scenario. The most common use case of reading code is (or should be) not caring about most of the implementation details until you need to; only then you have to go down the rabbit hole.
Longer functions force the reader to understand most of their context every time they get there, a problem especially when the function has a bunch of local vars.
Meh.
I’ll agree, docstrings are better for documenting a function than just a comment.
However, the author seems to jump through hoops in the next example to break one function into four, just to avoid some single line comments. Unless those code blocks make sense as functions (they’re used/duplicated elsewhere), you’re just making work for yourself. Why not turn it into 12 functions? One for each line of code?
I’m reminded of the admonition that there are only two hard problems* in computer science – cache invalidation, and naming things. The more functions you have, the more things you have to name.
The rest of it – name your magic numbers, use tuple unpacking, comment “why” instead of “what” – is good practice. I’m just not a fan of making functions just to avoid writing a comment.
* And off by one errors.
single use functions are fine; I often break 20+ line functions apart and it makes it easier to test and reason about, it’s not just to avoid comments: block comments are just a sign that the function might be getting too complex.
On the other hand, I often have wished that the author of the code I am reading had just kept their original 20 line function around instead of splitting it up into a zillion little functions that force me to constantly jump around to figure out what is actually going on.
it’s turtles all the way regardless; but it’s much easier to handle side effects if you have more numerous but smaller functions.
I prefer that because fully reading a module or component is not the most common scenario. The most common use case of reading code is (or should be) not caring about most of the implementation details until you need to; only then you have to go down the rabbit hole.
Longer functions force the reader to understand most of their context every time they get there, a problem especially when the function has a bunch of local vars.