Testing Python: Applying Unit Testing, TDD, BDD and Acceptance Testing

Chapter 4

Writing Testable Documentation

DOCUMENTING CODE IS a process that is considered difficult. On the one hand, extensive, in-depth documentation can benefit programmers using your code greatly. It can provide examples on how to use an API, for example, or design decisions explaining why the code behaves as it does. Alternatively, as code evolves, often quite rapidly, documentation quickly can become out of date and be rendered almost useless.

Fortunately, there is a happy medium. Documentation doesn’t need to be in the form of a huge document or website. It can be a combination of short formal documents (such as a website or wiki page), doc strings in methods, comments in code, and most importantly, the code itself. If your code follows good practices such as clear naming conventions and consistent use of styles, you can keep comments and documentation to a minimum. Adhering to best practices makes it clear to the reader what the code is doing, without the need for extra comments. That is not to say that comments and doc strings should never be used. Rather, they should be used sparingly and only on occasions that warrant their use, such as with a complicated method, or to explain why some code needed to be written a certain way or simply to offer useful information that you cannot convey in the method names and code you write. By keeping comments to a minimum, you avoid having out-of-date documentation. Maintaining the few locations requiring comments and documentation ...