Avoid over-commenting in Python
Avoid over-commenting in Python
www.pythonmorsels.com Avoid over-commenting in Python
When do you need a comment in Python and when should you consider an alternative to commenting?
11 comments
-
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.
-
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.
-
-
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.
-
sorry, this is a no-brainer. and Trey should really use global constants.
11 comments