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.
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.