Documenting Python code with docstrings
Python is a programming language with several features, including an easy-to-understand syntax and robust data structures, which can result in code that is efficient. While code written in Python is often clear and concise, it is still important to document it for the benefit of others who may need to read or maintain your code. Documentation can take many forms, from comments in your code to standalone documentation tools like Sphinx. In this article, we will discuss the importance of documentation and some best practices for documenting Python code.
Why document code?
The first question you might have is: why bother documenting code? After all, if the code is written well, shouldn’t it be self-explanatory? While it is true that well-written code can often be understood without extensive documentation, there are several reasons why you should still take the time to document your code.
First, documentation can help you and others understand the purpose of a code block, even if the code itself is not self-explanatory. In some cases, comments can make the code more understandable by providing context that would otherwise be lost. For example, you might use a comment to explain why a particular line of code is necessary, or to provide an example of how the code is used.
Second, documentation can serve as a living record of your code’s evolution. As your codebase changes over time, documentation can help you and others track those changes and understand how the code has changed. This is particularly important when working on large or complex codebases, where it can be difficult to keep track of all the changes that have been made.
Third, documentation can help you plan and structure your code. By taking the time to document your code, you can think more carefully about its organization and design. This can lead to more maintainable and scalable code in the long run.
Documentation tools
There are a number of different tools that you can use to document your Python code. The most popular of these is Sphinx, which is a tool for generating documentation from source code. Sphinx can be used to create both online and offline documentation, and it has a number of features that make it well suited for documenting Python code. For example, Sphinx can automatically generate documentation from docstrings, and it can link to code definitions automatically.
Another popular tool is epydoc, which is similar to Sphinx in many respects. However, epydoc has a number of features that make it more suitable for smaller projects. For example, epydoc can be used to generate documentation from a single source file, without the need to create a separate documentation project. Pygment can also generate documentation from a single source file.
Python docstrings
One of the most important things to document in Python code are docstrings. Docstrings are strings that are used to document a code block, and they are typically placed at the beginning of a code block. For example, the following code has a docstring that explains what the code does:
In this example, the docstring explains what the compute_average function does. This is important, because it means that someone reading the code will not have to guess the purpose of the function. Sometimes, the function name is self-explanatory as in this case but the point is still valid for more complex functions.
Docstrings can take many forms, but they typically follow a standard format that includes a one-line summary, a longer description, and a list of parameters and return values. For example, the docstring for the compute_average function could be written as follows:
As you can see, this docstring provides a lot more information than the previous one. In particular, it provides a description of what the function does, as well as a list of parameters and return values.
It is important to note that the format of a docstring can vary depending on the conventions that are followed in your project. For example, some projects might use a different format for the list of parameters, or they might place the docstring after the code block instead of before it. However, the general idea is always the same: to provide information about the code that would otherwise be lost.
What can you do with docstrings?
In addition to being used to document code, docstrings can also be used to generate documentation automatically. As we mentioned earlier, Sphinx can be used to generate documentation from docstrings. This is a very powerful feature, because it means that you can write your documentation once and have it be used in both your code and your documentation.
Another tool that can be used to generate documentation from docstrings is pydoc. Pydoc is a standard library module that can be used to generate documentation from Python code in HTML files.
List of resources
- Pandas docstring guide
- PEP 257 — Docstring Conventions
- Google style docstrings
- Compilation of docstrings styles
Conclusion
Documenting Python code is an important part of any development process. By taking the time to document your code, you can make it more understandable, easier to change, and more scalable. There are many different tools that you can use to document your code, but the most important thing is to use whatever tool works best for you and your project.
