Good and bad code - Sylvain Viollon¶

Tags: python, pun

(Summary of a talk at the Dutch Python meeting)

What is good code for you? What is good code for your users?

Of course, Sylvain reuses lots of open source code. He wants code that works and that helps him build his project. And good code is reliable and safe. And he wants, professionally, to have high quality code as he has customers that have to use it.

Bad code is code he can’t reuse. It is broken and doesn’t run, for instance. Slow. Insecure software. Or is doesn’t actually do what it claims to do. (He had a bad experience with a python SOAP library that wasn’t generic; it only worked with one specific kind of SOAP message, it didn’t implement the standards).

So… good code is code that actually works and that fits his needs (so: it doesn’t only fit the original author’s needs). And… publish your good code, so upload it to pypi.

Code that works means tested code. And don’t forget to check that it works in real life! Some testing libraries, especially in web development, don’t mimick the real webbrowser good enough. So the tests run, but the software doesn’t work in real life.

And, regarding testing, don’t write tests only to get 100% code coverage. 100% coverage doesn’t really tell that much. (Note by Reinout: I don’t agree. Less than 100% coverage still tells you that some code is completely untested.)

Some code is hard to test. Good code is easy to test. Perhaps you have to rewrite your code a bit to make it easier to test.

Important to keep in mind: don’t write fantasy code. Code that covers hypothetical use cases. Only spend time writing code that will actually be used. And don’t try to handle all corner cases if that’s not needed; your code will probably be faster and more robust if you don’t.

Good code is also well-documented code. Write simple documentation to get you started. And, according to Sylvain, doctests are not good for simple documentation. Doctests are fine, just not for simple documentation. Very helpful when investigating a Python package: maintain a changelog and make sure it is easy to find.

Listen to your users, to the developers that are using your code. Listen to them and answer them so they can use your code. And change your code if needed because of the feedback. Or delegate that role to someone else if they want to be the one maintaining it. An even more clever way is to make your code extensible so others can do custom stuff with your code.

Handy ways to make your code extensible are setuptools entry points (note Reinout: see my explanation of entry points) and the Zope component architecture. And don’t ever hardcode anything.

Good comment from the audience: good code is often developed iteratively. It slowly becomes good. It doesn’t start out right away as the most perfect piece of software possible.