Why Documenting Your Code Is So Important

00:00 Welcome to Part 2 of the Real Python tutorial for Documenting Your Python Code. Now, let’s address why documenting your code is so important.

00:09 Guido van Rossum, the Python creator, once said that “Code is more often read than written.” This is a very interesting observation. Why? Well, when you are writing code, you’re writing it primarily for two different audiences: your users and your developers. That includes yourself.

00:27 Both of these audiences are just as important as each other. Now, hands up if you have ever reviewed old code that you have written and thought, “What was I even doing there?” Now, imagine if you were someone else looking at the same code.

00:42 If you are having issues reading it, imagine someone who didn’t write it and how they would go understanding it.

00:47 This point of view, however, has two sides. Imagine you find a library online that on the surface appears absolutely fantastic. Naturally, you start to try to use it. Now imagine looking for examples, release notes, write-ups—anything to give you some direction on how to use it to accomplish a task for which you thought, initially, it was so perfect. After searching for a while, you realize the documentation just isn’t available.

01:12 This could be frustrating and could potentially deter you from using the library at all, regardless of how good it may be.

01:20 Daniele Procida summarized this situation quite well. “It doesn’t matter how good your software is, because if the documentation is not good enough, people will not use it.” Much like the falling tree in the forest, if a Python library is not being used, does it actually build? Moving forward, this guide will show you how to properly document your Python code, whether it be a 10-line script or a 10,000-line library, to help prevent any of your potential users from ever experiencing that frustrated feeling.

01:49 Join me in the next video to begin exploring the next segment: commenting versus documenting code.