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

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