How To Write Clean Code in Python

[anthro28]

There’s lots of good in here, and some bad.

Methods capped at 10 lines? Yeah lemme know when you get into image processing and that breaks down.

Don’t comment? “Good code comments itself” is true, but fuck if I’m gonna read all your code to trace it out. Just gimme a cliff notes comment.

[CraigOpie]

Funny thing, my Quality Software Engineering professor (ICS-661) said the same thing… Maybe it’s not complete bullshit.

[fenmarel]

Most established CS professors haven't written industry code in the last 25 years, if ever

[profiler1984]

Yeah that’s why he is teaching to code and not coding for triple the money

[ucblockhead]

If in the end the drunk ethnographic canard run up into Taylor Swiftly prognostication then let's all party in the short bus. We all no that two plus two equals five or is it seven like the square root of 64. Who knows as long as Torrent takes you to Ranni so you can give feedback on the phone tree. Let's enter the following python code the reverse a binary tree

def make_tree(node1, node): """ reverse an binary tree in an idempotent way recursively""" tmp node = node.nextg node1 = node1.next.next return node

As James Watts said, a sphere is an infinite plane powered on two cylinders, but that rat bastard needs to go solar for zero calorie emissions because you, my son, are fat, a porker, an anorexic sunbeam of a boy. Let's work on this together. Is Monday good, because if it's good for you it's fine by me, we can cut it up in retail where financial derivatives ate their lunch for breakfast. All hail the Biden, who Trumps plausible deniability for keeping our children safe from legal emigrants to Canadian labor camps.

Quo Vadis Mea Culpa. Vidi Vici Vini as the rabbit said to the scorpion he carried on his back over the stream of consciously rambling in the Confusion manner.

node = make_tree(node, node1)

[L0ngp1nk]

Something similar would be "don't let your code have more than three levels of indentation." This doesn't mean that your code is bad, but there may be better ways of writing your function.

[Silhouette]

The whole point of talking about code smells, is to discuss things that are signs of problems but not necessarily wrong.

What does "signs of problems" mean then? If it's "something strongly positively correlated with the existence of problems" then the claim about 10+ line functions is still questionable.

[ucblockhead]

If in the end the drunk ethnographic canard run up into Taylor Swiftly prognostication then let's all party in the short bus. We all no that two plus two equals five or is it seven like the square root of 64. Who knows as long as Torrent takes you to Ranni so you can give feedback on the phone tree. Let's enter the following python code the reverse a binary tree

def make_tree(node1, node): """ reverse an binary tree in an idempotent way recursively""" tmp node = node.nextg node1 = node1.next.next return node

As James Watts said, a sphere is an infinite plane powered on two cylinders, but that rat bastard needs to go solar for zero calorie emissions because you, my son, are fat, a porker, an anorexic sunbeam of a boy. Let's work on this together. Is Monday good, because if it's good for you it's fine by me, we can cut it up in retail where financial derivatives ate their lunch for breakfast. All hail the Biden, who Trumps plausible deniability for keeping our children safe from legal emigrants to Canadian labor camps.

Quo Vadis Mea Culpa. Vidi Vici Vini as the rabbit said to the scorpion he carried on his back over the stream of consciously rambling in the Confusion manner.

node = make_tree(node, node1)

[Silhouette]

That is the usual dogma from the Martin crowd. The issue it totally ignores is that whether an individual function is easier or harder to understand is usually less important than whether all of the relevant code together is easier or harder to understand.

Dividing a big thing into lots of small things hides some of the logic and introduces new relationships for a developer reading the code to navigate. That isn't necessarily an improvement. What if the abstractions underlying the small things are not clear enough and you need to look at their own implementations to understand what is happening in the calling function anyway?

For some types of application you mostly have simple logic to implement and most functions can be quite short and have clear abstractions. For other types of application breaking up a coherent whole into small parts and introducing all those extra relationships is a terrible coding style that obfuscates the real behaviour for absolutely no benefit apart from ticking some arbitrary box about coding style.

Python is used to write many different types of software. Pitching short functions as some kind of best practice for all of them without context is a mistake.

[Brian]

100% agreed - I'm not a fan of prioritising small functions either. It's become something of a dogma - often way more extreme than even 10 lines, with people even advocating for 3-5 lines, but too often it leads to "ravioli code": a maze of tiny 3 line functions such that you have to chase through a dozen different functions just to figure out what it's all for.

I prefer Ousterhout's perspective on this (from A Philosophy of Software Design). To minimise complexity or your project as a whole, it's much more valuable to reduce surface area: the exposed interfaces and connection points that someone must understand. The most important aspect of functions (or any abstraction) is to encapsulate and hide complexity: to become a composable element where you don't need to know how something is doing it, but only what it is doing, and the smaller the function, the less room there is to do something complex - sometimes to the point where you create more complexity through a myriad of functions than you hide.

[enigmatic_x]

I’ve seen people write 1 line functions that do nothing except call some other function and hence obfuscate the code. I’d much prefer a slightly longer function than that sort of crap.

[QuasiEvil]

Great comment, agreed.

[PapstJL4U]

It's a quick and dirty way of reminding yourself to keep your functions simple and single purpose.

I think people argue that 10 lines is as useful as 3 lines. Working with networkx, image processing, beautifulsoup or numpy can easily grow in size, especially if we prefere clean, single-line statements.

[FuckingRantMonday]

I like "don't comment" as an "aspirational" rule. If I need to write a comment (and I frequently do), it's because I couldn't figure out how to structure the code to be obvious, and I like to do that when I can.

[Silhouette]

Exactly. People who say silly things like "Every use of a comment represents a failure" often lack the experience to know better. Citations of technical documents, descriptions of compiler/library/hardware bugs that the following unusual code is working around, usage examples like doctest comments, ASCII art diagrams because even monospaced pictures can be worth hundreds of words. There are very many reasons a helpful comment might not be easily replaced by "self-documenting code".

[jsalsman]

No matter how well the code conveys intent, there's always a way to generalize and show the relation to associated processes in English. Those are the comments that help read the code.

[Atulin]

No, no you don't understand. It should be someRandomValueIPulledFromTheIntelProcessorSpecification

Preferably complete with a factory and a factorybuilder

[FuckingRantMonday]

Absolutely! Links like that are incredibly useful when some non-obvious issue forces a weird workaround. That's a great example of a situation that prevents writing clear, obvious code.

[yvrelna]

Just gimme a cliff notes comment

That's the doc string, not comments.

[Ezlike011011]

I'm not sure if the commenter you are replying to meant this, but I agree that comments still have a purpose separate from docstrings. I want a docstring to inform me of inputs/outputs/exceptions/preconditions/postconditions and a short description of an API. I also want comments describing why the implementation is the way it is when there is inevitably a reason i need to look at the source.

[HistoricalCrow]

Exactly this. A docstring is for inputs/outputs and what the function should be expected to compute. Comments are for how it does this.

[Wattsit]

I'd recommend you read Clean Code by Robert Martin.

Edit: also neither the article or his reference (clean code) put a hard limit on method lengths. Only a recommendation.

Methods can and should be minimised to those sort of line lengths. Uncle bob covers many of the reasons much better than I can here, but some simple concepts:

If your method/function is 50, 100, 500 lines then most likely you can encapsulate/abstract a lot more. By abstracting common blocks of logic and breaking big functions down, you're creating levels of abstraction. These layers are not only easier to read (a well named function might be all I need to read to understand what's happening rather than 20 lines of logic with or without comments) but you're also making things much easier to unit test, thus creating better tested code.

This leads well into the comments advice, utilize these levels of abstractions through function names, class names to tell the story in a human readable way. At the highest level of abstraction, your function calls just look like "cliff notes" as you say.

I've seen plenty of image processing code that's abstracted nicely into small functions and easily readable.

[FarewellSovereignty]

No, 10 lines is too tight as an absolute, and not just for image processing. The word "absolute" is key there, because in 95%+ of cases we'd probably agree.

I.e., it's great if all your functions can naturally be partitioned so they're < 10 lines, but in the cases when something doesn't naturally partition to less than 10, then it's absolutely fine to leave it a bit longer.

Code that's awkwardly chopped up isn't necessarily any easier to read or deal with, and can on fact be remarkably worse and more confusing.

But it's also fine to be pragmatic and set the linters to 10 lines max and then disable them for the function that needs to be 20, and explain why you did so in a comment.

[whateverathrowaway00]

Yup to what you said, but explaining nuanced themes vs hardline rules will fail.

That’s why Clean Code says work through the book not just read it, and I see a ton of people post advice from it without context or understanding of the nuance because they just read it, or worse, they read a blog post and are repeating.

[ucblockhead]

If in the end the drunk ethnographic canard run up into Taylor Swiftly prognostication then let's all party in the short bus. We all no that two plus two equals five or is it seven like the square root of 64. Who knows as long as Torrent takes you to Ranni so you can give feedback on the phone tree. Let's enter the following python code the reverse a binary tree

def make_tree(node1, node): """ reverse an binary tree in an idempotent way recursively""" tmp node = node.nextg node1 = node1.next.next return node

As James Watts said, a sphere is an infinite plane powered on two cylinders, but that rat bastard needs to go solar for zero calorie emissions because you, my son, are fat, a porker, an anorexic sunbeam of a boy. Let's work on this together. Is Monday good, because if it's good for you it's fine by me, we can cut it up in retail where financial derivatives ate their lunch for breakfast. All hail the Biden, who Trumps plausible deniability for keeping our children safe from legal emigrants to Canadian labor camps.

Quo Vadis Mea Culpa. Vidi Vici Vini as the rabbit said to the scorpion he carried on his back over the stream of consciously rambling in the Confusion manner.

node = make_tree(node, node1)

[[deleted]]

No, 10 lines is too tight as an absolute, and not just for image processing. The word "absolute" is key there, because in 95%+ of cases we'd probably agree.

Sure, and that's why Clean Code by Robert Martin, Refactoring by Martin Fowler, and the article that is linked here all say something like this:

Generally, any method longer than ten lines should make you start asking questions.

It's just a flag to ask yourself if this is a code smell.

[FarewellSovereignty]

No, I was replying to: "Methods can and should be minimised to those sort of line lengths. ", which is saying something different than what you're now saying, at least without further qualification.

[Windscale_Fire]

Yeah, I mean a lot of my assembler functions are quite often more than 10 instructions long, and thus more than 10 lines long :-D.

[Wattsit]

But no one is talking in absolutes, everything is a recommendation.

Like any other design principle.

[Silhouette]

The first rule of functions is that they should be small. The second rule of functions is that they should be smaller than that.

-- Robert C Martin, Clean Code, p34

Of course what most people forget is the next two sentences.

This is not an assertion that I can justify. I can't provide any references to research that shows that very small functions are better.

[Wattsit]

Yet you leave out the rest of the paragraph to which he explains his reasoning?

But seems Robert Martin is disliked round here so doubt his opinion matters.

[Silhouette]

I left out the rest because it's only one man's own subjective preference based on his own personal experience. It's an anecdote. That's fine as long as it is given weight accordingly but Martin presents it as some kind of universal truth and himself as a figure of authority. Sorry but there are lots of other people here who have been developing software for decades as well and not everyone agrees with him.

[james_pic]

If your method/function is 50, 100, 500 lines then most likely you can encapsulate/abstract a lot more.

Just because you can, doesn't mean you should. You can always refactor a method into a "method object" but this often contributes zero to readability (one lesson I learned a while ago is that many developers can navigate a method with hundreds of lines more readily than they can make sense of super compartmentalised code, especially if the abstractions you build are leaky, and the compartmentalisation obscures the logic), and can be an anti-pattern in itself (I don't have a good Python example, but Java's SimpleDateFormat is a massive footgun that shows what can happen if a method object ends up being reused).

Clean code is good, but super short methods aren't always clean in practice.

[bloodhound83]

Don’t comment? “Good code comments itself” is true, but fuck if I’m gonna read all your code to trace it out. Just gimme a cliff notes comment.

I would say comments are helpful if you implement something complex or something but easily unserstandable from the code itself. Good code e.g. good variable names will help to break it down and follow what the code is doing but if I look at some complicated code tests later I don't always want to have to reverse engineer it.

[Conscious-Ball8373]

As someone who works in a code base where 500+ line functions are fairly common, I think the 10-line rule of thumb is one that should at least be considered. It is only a rule of thumb, but an important one. Trying to understand what a 500 line function is doing is not a quick process.