Readability counts

1. Readability counts

Another important step to writing a maintainable project is readable code.

2. The Zen of Python

Luckily, Python has a big focus on readability, and it comes with a list of guidelines to help write good code. These guidelines are known as the 'Zen of Python', and you can view them through the command 'import this'. Here we see an abridged version. Notice the item stating, 'readability counts', and the rest of the items can guide us in this quest for readability.

3. Descriptive naming

One way to aid in readability is with good naming. Look at these 2 functions. Both implement the same logic. However, if we believe 'readability counts', then the is_boiling function is a better option. The is_boiling function describes what it's doing thanks to descriptive naming. This is known as self-documenting code. However, remember that under-commented is a bigger issue than over-commented code; if you're ever in doubt, add comments. A warning about descriptive names. It's possible to go too far. Modern IDEs have auto-complete so it might not seem like a burden to type long names, but long names can make code hard to read, as you see here. Note, even if your code is self-documenting, your users will appreciate the ability to call help and see all the good information a docstring can provide.

4. Keep it simple

Another way to keep your project readable is by writing in simple maintainable units of code. Let's take a look at an example by writing a function to make a pizza.

5. Making a pizza - complex

Take a look at this code to make a pizza. Notice that the full definition doesn't fit on the slide. Although we're working with a small screen, not being able to fit your function on the screen is a sign that it maybe should be refactored. A less obvious issue is that we have a few different processes happening that could stand on their own. We're making dough and then making a sauce; we might want to be able to make dough outside of the pizza process. Let's do some refactoring.

6. Making a pizza - simple

Take a second to look at this refactored function. It's easier to see what's happening, in both a functional sense and a literal one since we were able to fully fit it on the screen. By breaking processes out into their own descriptively named functions we can see the high-level process of making a pizza at a glance. An additional benefit of defining these smaller functions is that we now have more modular code that we can easily plug into different recipes that might call for our homemade marinara. These also make writing tests easier, which we'll soon be covering.

7. When to refactor

Our rewrites came about thanks to a couple warning signs. They were that our function was a bit long and we had separate processes happening. You should strive for your functions to accomplish one and only one thing. In our pizza example, we were using comments as 'section headers' to denote different processes; if you're ever doing that then it's a good bet that your code should be split into smaller functions. Another warning sign that your function is doing too much is if it's hard to think of a good meaningful name for it. Unfortunately, you might not notice your code is hard to read until trying to read it the next day. Just strive to do your best, and to repeat once more: document your code with comments and docstrings.

8. Let's Practice

We just covered some important topics about writing readable code. Let's practice.

Create Your Free Account

By continuing, you accept our Terms of Use, our Privacy Policy and that your data is stored in the USA.