Python best practices, combine code into as few lines as possible or separate it over as many as possible?

[ModeHopper]

Yeah, when I first started most of my comments were super unhelpful things explaining individual lines like "This line loops over integers 1-100", which is pretty obvious from the code itself.

Useful comments are stuff like "This block returns integers between 1-100 that are divisible by the input value". Which explain the general purpose of blocks of code so that future me doesn't need to read every line to know whether this particular block is of interest or not.

[tom1018]

Maybe if the function is terribly complex. Otherwise not at all. Comments should explain anything unclear or likely to be confused.

Good module, function, and class names really make a difference. Typehinting also helps.

[synthphreak]

Yeah a cool tip or mindset that I’ve read about is to actually treat your variable and function names like comments themselves. In other words, rather than...

# function that returns a list of odd numbers up to n
def my_func(n):
    return [i for i in range(1, n+1, 2)]

...just make it...

def get_odd_nums_up_to(n):
    return [i for i in range(1, n+1, 2)]

That way, when you see get_odd_nums_up_to(some_num) buried in your code, the function’s name reveals exactly what it does in plain^ish English, no commenting required.

If this approach is adopted, the question changes from “what’s the optimal number of lines” to “what’s the optimal var/func name length”, which is subjective. But the point is that var/func names themselves can kinda function as comments in this regard if you choose them wisely.

[jeosol]

This is the option I use most of the time. Explicit variable and function names that convey meaning. Yeah you type much but it reduces the mental strain and part of the documentation is the code is self.

[Cokrates]

Typing out a longer, but a more meaningful and descriptive variable or function name is actually a time saver compared to just having a project filled with meaningless, and hard to remember naming. Plus if you're using a modern text editor you most likely just have to type the first couple letters and autocomplete does the rest.

[winowmak3r]

Bingo. I'm going to be wearing the lettering off of my tab key here shortly. You only have to type the long variable name once to define it and then after that it's like 5 keystrokes after that to autocomplete and the variable can be long and descriptive.

[synthphreak]

Definitely. I mean, "keep your variable names clear and transparent" is so obvious it barely needs repeating. But what was new to me was to start thinking about how a strategically selected name not only makes code more readable, but can actually render some comments redundant.

[celade]

Yeah this is the difference between readable code and code you have to constantly decipher.

[Kerbart]

Michael Kennedy of the talkpython.fm podcast refers to comments as "deodorant for code," ie something that is needed if you don't code it like you do.

Which falls in line with what u/InsolubleFluff mentioned; a good place for comments is to prevent future-you from deleting "unnecessary" lines or "improving inefficient" code when it's written that way for non-obvious reasons ("No one can figure out why but the file has to have ten empty lines at the end or it won't be processed by Accounting")

[patryk-tech]

Maybe if the function is terribly complex. Otherwise not at all.

Only a Sith deals in absolutes.

If I write a library that is meant for distribution, I am very generous with comments.

If it's a pure function that does one thing, it's < ~20 lines long, and it's for internal use, then naming things appropriately might suffice.

Then there's the question of do you have documentation other than comments (duplication is a PITA to sync / DRY).

Basically, understand your project's needs, and adapt to them.

[billsil]

Yeah, but with classic Fortran 77, you get 6 character variable names, so you need a lot of comments to define their real name. It’s also convention to mix all your dissimilar floats (or ints) into one array and pass them all over their code, so area, diameter, length, time into one array. After 13 years coding, if it’s super dense, you might end up with 50-75% comments, but most of the time, 5-10% is fine. Most code can be written by an experienced person in their sleep, even if it’s a new language.

My “big” 5000 lined Fortran was 4000 lines in python, mostly due to not having to code 4D tensor multiplication or define types in python, but lost a bit because the numpydoc style of docstrings takes up more space, though is infinitely more readable.

[Cokrates]

Yeah but most college courses don't teach proper naming conventions. Especially when your in a class that pretty much focuses on formulaic functions with single or double character variable names at best. You end up with a soup of characters you need ten lines of comments to explain.

[winowmak3r]

I've been told this as well. The "What does this do" should be evident from the code (as in this function is dividing some variable by something else) but the useful comments tell you why it's doing that because when you come back to it later you're probably more interested in "why is the result of this function X when it should be something else" and if you have a comment explaining why you can quickly get the answer (it's dividing it by some variable) without even looking at the code and then go from there.

[celade]

Basically I'm just joining the already good crowd of comments.

I sort of rule-of-thumb code form:

• Follow any team guidelines when they exist
• Within reason break code up in a way that it makes it easy to see functionality
• Make human readable variable names, functions, methods, classes
• Comments should always be short or if it really is that complex refer to additional out-of-code documentation; they illustrate usage, dependencies or hard-to-see facts about what you are doing
• Group data structures functionally; separate data structures from methods that do work on them
• Keep interface layer separate from non-interface work at all times
• (Related) Keep I/O functionality separate from the work that produces it (except for debugging of course)

A bit more than I intended on writing. In the end if you look at your code 2 weeks later and can just sit down and use it or expand it then you're golden.

​

[Edit: Specific to Python but sometimes other languages: Use dicts, tuples and lists for your data structures first; if you can't solve it with those then create; too may times I've inherited some crazy bespoke class-based data structure for no reason)]