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.
I agree completely that, when done well, smaller functions can make code easier to work with for all of the reasons that you have mentioned. When not done well, however, I still have to read through all of the same code to figure out which part has the implementation detail that I need to care about, but now it has been scattered about instead of collected into one convenience place.
I also like to use log statements or error messages as a way to describe what’s happening.
Comments are only visible in the exact spot where they’re written, whereas decent names or log statements become visible in a second place, which makes them more valuable, but also increases the chance of them being kept up-to-date.
Praise the log and observability lords!
People really underestimate how useful logs are in almost every context.
until it isn’t
multiprocessing humbles the plans of mortal men
(Initially thought you were being sarcastic.)
Agreed. Name things. And split up code into chunks with a sane lenth and have these methods do about one thing. And know the program language well enough so you don’t need to do it in an unnecessarily complicated way. You can get rid of most of the inline comments that way. Not sure if this translates to docstrings though, if you’re generating some reference or something. Yeah, and please tell me the “why” I can read Python code, so I can pretty much already see “what” it’s doing.
don’t break up long functions
Some things are so complex they can only be understood in long functions. Break up the long functions and what’s going on is lost.
Only have one example where the complexity is best left alone, the heart of a requirements management package. Where the whole is greater than the sum of it’s parts. Or the parts lose meaning if taken in isolation.
docstrings
surprised flake8+black even allows a comment as the docstring.
Prefer triple single quotes over triple double quotes. But black slapped me back into conformance. Of course i’m right, but evidently that’s not good enough. So triple double quotes it is.
Slap me often and hard enough, i
learnconform.Except for build backends and requirements management.
sorry, this is a no-brainer. and Trey should really use global constants.
