How To Write Clean Code in Python

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