Readability counts. - The Zen of Python
That code readability is important should not come as a surprise to you. For many people, it’s why they picked up and continue working in Python. Few other languages place such emphasis on how the code reads. However few of you would argue that its so important that it should take first priority in a project. Beautiful code that’s broken or fails to deliver on the business requirements is a happy waste of time.
So when should you start addressing issues like code formatting? Surprisingly, right away.
No, bad code formatting is not going to cause your startup to lose funding or discourage customers from renewing. It is friction though, and as a source of cognitive drag it represents a real cost and risk factor in the development process. And like a squeaky door[1] this friction won’t go away until you apply a little oil.
But let’s be clear, in that _starting _to address these issues is something you can and should do right away. This is different than spending time making sweeping changes.
Instead, the first step is setting up a linter as part of your development workflow, preferably part of your automated workflow. If you’re wondering what a linter is, its a tool that checks source code for style and formatting issues, e.g. too many spaces around operators, the kind of stuff that _usually _doesn’t affect how the program runs but does affect how it reads.
Here I’d recommend using flake8[2], which will check not only for PEP8[3] compliance and report on formatting issues, but also perform some basic static analysis. Static analysis takes linting a step further and analyzes the structure of the source code. Instead of identifying bad indentation, static analysis will identify that your code references a module but failed to import it - this _is _the kind of stuff that will affect how your program runs!
Concretely, add flake8 to your project requirements where it makes sense, and run the tool against your code. If you find only a few minor issues, go ahead and fix them. However you may see a slew of issues which can be… daunting.
Don’t sweat it! After identifying and fixing runtime error-causing issues like the aforementioned missing import, the next step is to silence the errors. That’s right, silence them.
Using flake8’s configuration in either a tox.ini or similar file (see the docs, of course) exclude the various sub modules of your project one by one, not forgetting to explicitly exclude modules like migrations, which would be an unproductive and unnecessary pain in the tucchus to keep de-linted. Then make sure when you run flake8 it runs without error.
Now here’s the key: when you spend significant time working in a module, remove that module from the exclusion list so that flake8 shows you the errors there. Over time you can work your way through the project making it significantly more readable without making a project of it.
Cheers:
Ben
[1] Check out this guy’s YouTube channel dedicated to door maintenance!
[2] flake8: http://flake8.pycqa.org/en/latest/
[3] PEP8, Style Guide for Python Code: https://www.python.org/dev/peps/pep-0008/
Learn from more articles like this how to make the most out of your existing Django site.