An initial version of this article appeared as a Pybites email first. If you like it join our friends list to get our valuable Python, developer and mindset content first …
How following the Zen of Python will make your code better, a lot better.
This epic set of axioms (triggered by typing import this in the Python REPL) says a lot about code quality and good software design principles.
Although each one is profound, let’s look at a few in particular:
Explicit is better than implicit.
This is an important one. If we don’t state things explicitly we miss obvious facts when looking at the code later, which will lead to mistakes.
This axiom is much about expressing intent and being informative for the next engineer, who will often be you!
You read software way more often than you write it. Plus the code you do write is for humans first and machines second.
Hence using meaningful variable / function / module names, and structuring your code properly, matters. As the Zen also says: Readability counts (and I think Python’s required indenting, like it or not, helps with this too).
Simple is better than complex.
Software inherently grows complex over time. I think keeping things simple as a system grows, is the greatest challenge we face as programmers.
Following this criteria alone is often the only way to keep a system maintainable!
Sometimes you cannot avoid a certain level of complexity though. That’s where great libraries design great abstractions. The underlying code is complicated but it’s hidden behind a nice usable interface (great examples are Typer, FastAPI, rich, requests, Django, etc).
As the Zen says: Complex is better than complicated, and the isolation of code and behavior those interfaces create, are a testament to the other Zen axiom that Namespaces are one honking great idea.
Regarding namespacing see also this discussion I recently opened about Python imports.
Flat is better than nested.
This is one of the things I often highlight in my code reviews. Deeply nested code (the horrendous “arrow shape”) is an indication of overly complex code and should be refactored.
Did you know that Flake8 is a wrapper around PyFlakes, pep8 and Ned Batchelder’s McCabe script?
McCabe checks complexity and anything that goes beyond 10 is considered too complex.
So the good news is that you can measure this using Flake8’s --max-complexity option.
Often it’s just a matter of breaking code out into more helper functions / smaller pieces.
You can also make your code less nested by using more early returns and constructs like continue and break.
Similarly Zen’s Sparse is better than dense is all about keeping your code organized and using line breaks for more breathing space.
For example, in a function, do some input validation -> add two line breaks -> do the actual work -> add two line breaks -> handle the return.
Just adding some more space / using blocks, your code will be so much more peaceful and readable, an easy win.
Same with clever one-liners, they are generally not readable. Do your fellow developers (and future you) a favor and break them out over multiple lines.
Special cases aren’t special enough to break the rules. Although practicality beats purity.
I like this axiom a lot because we all start software projects with a lot of good intentions, but as complexity grows, and adjusting to (inevitable) user requirements on the fly, we’ll inevitably have to make compromises.
It’s good to set the standards high but shipping fast and being responsive to changing needs also requires you to be a Pragmatic Programmer (as per one of my favorite programming books).
Regarding software in the real world, I like what somebody said the other day after working with us:
Most valuable thing I learned from you and the program was not only iterating quickly but having it be in the hands of users.
PDM client on the importance of shipping code requiring a good dose of practicality.
If the implementation is hard to explain, it’s a bad idea + If the implementation is easy to explain, it may be a good idea.
Another important one. We often think we can implement something right the first time, but sometimes we don’t understand the problem good enough yet (or we try to be clever lol).
A good test is to see how easy you can explain the design to a colleague (or rubber duck lol). If you struggle, maybe you should not start coding yet, but spend some more time at the whiteboard and talking to your stakeholders.
What’s the real problem you’re trying to solve? How will it be future proof? The latter usually becomes more apparent as more code gets written.
We talk about this in our live developer mindset trainings and on our podcast as well.
I hope this made you reflect on Python code and software development overall.
We should be grateful to Tim Peters for writing these axioms up and for Python’s creator + core developers for so elegantly implementing these almost everywhere you look in the Standard Library and beyond.
It makes Python a joy to work with and the error ratio to be consistently lower. In Python things usually just work which makes code written in it more maintainable which is awesome 😎😍
What’s your favorite Zen axiom and/or has changed the way you code?
Hit me up on Twitter or on Mastodon and let me know …