The Case for Best Practices

By Kristian Rother

When I was 16, I started writing a computer game on a C64 computer with a couple of friends. At first, programming was easy. We created graphics, levels, and an intro. But as the program evolved, programming got increasingly harder. Every time the program terminated with a bug, I had to restart the computer, reload the compiler, rewrite a few lines of code and try again. Needless to say, soon I got so frustrated with the program that I threw it into a dusty corner. Only much later I learned that a more professional way to program would have been to plug a cartridge with a reset button into the computer. The better reset buttons would start the compiler right away and thus cut the vicious programming-rebooting cycle short. This simple tool made the cycle of programming and debugging a lot shorter. I will call this kind of shortcut a Best Practice.

Do we need Best Practices in Python?

Today, with easy-to-use programming languages like Python, do we still need Best Practices? Imagine we wanted to write our own computer game in Python. One of the first things we need to do is to load images from files and combine them. With the pygame library, two images can be combined in just five lines. Let us consider a simple code example taken from the maze_run repository on GitHub:

^{from pygame import image, Rect}

^{maze = image.load('my_maze.png')}

^{player = image.load('player.png')}

^{maze.blit(player, Rect((32, 32, 64, 64)), Rect((0, 0, 32, 32)))}

^{image.save(maze, 'merged.png')}

However, there are problems with this program (merge_images_buggy.py in the repository): It does not work as intended. More specifically, there are three issues with it:

• The name of the first image file is wrong

• The program will not run on a newly installed system, because pygame is not installed there

• The program contains no documentation, so a new developer does not know what the program was intended for

If these three issues (and many more) possible issues with a five-line program, how many more will there be if we start writing longer Python programs? Obviously, the problem will get worse with increasing size. It is intriguing that none of the three problems above can be solved by looking at the program code alone. This is why we need to consider other practices and tools in order to fix the problems above. In Python, there are (at least) three big families of Best Practices:

1. Debugging - or getting a program to work correctly. In Python, the Best Practices for debugging range from dealing with Exceptions over well-placed print statements to stepping through the code in an interactive debugger.

2. Automated Testing - writing code that checks whether a program behaves in the expected way and complains, if not. There are many Best Practices to write automated tests for a given purpose. Fortunately, the py.test framework helps to express most tests in a very concise way.

3. Maintenance - making sure that a program stays editable, executable and usable over a longer period of time. Some Best Practices, like the version control system “git” are accepted in all programming languages. Other tools like “virtualenv” and “sphinx” are tailored for Python projects and make your programming time a lot less arduous.

The table shows a collection of Python engineering practices, ranging from worst (left) to good practice (right). To improve our little program, we could first add print statements to debug the exception, write an automated test that checks the program for bugs, create a git repository for our project, add a simple README file to document the code and so on.

The outcome will be a lot more than the five lines we had initially: We are building a support structure that makes our small program more robust. Choosing the right engineering tools for a given project is what I call "Best Practices".

Conclusion

Taken together, as Python programmers, we still need to take care about the tools we are using. Knowing and using the Best Practices is as necessary for successful programming as learning Python commands and constructs.

You can find more on debugging, testing and maintaining Python programs in my book Pro Python Best Practices, available now.

About the Author

Dr. Kristian Rother is a freelance Python developer and trainer with over 30 years of experience. He is based in Berlin, and believes that everybody can learn programming.

This article is excerpted from Pro Python Best Practice: Debugging, Testing and Maintenance by Kristian Rother, ISBN 978-1-4842-2240-9.