Effectively documenting Python code
Finding an effective way to document code is always important. The challenge is to develop a comprehensive yet simple way to develop Python code. Let's first look into Python comments and then docstrings.
Python comments
In contrast with a docstring, Python comments are not visible to the runtime compiler. They are used as a note to explain the code. Comments start with a # sign in Python, as shown in the following screenshot:
Figure 1.4 – An example of a comment in Python
Docstring
The main workhorse for documenting the code is the multiline comments block called a docstring. One of the features of the Python language is that DocStrings are associated with an object and are available for inspection. The guidelines for DocStrings are described in Python Enhancement Proposal (PEP) 257. According to the guidelines, their purpose is to provide an overview to the readers. They should have a good balance between being concise yet elaborative. DocStrings use a triple-double-quote string format: (""").
Here are some general guidelines when creating a docstring:
- A docstring should be placed right after the function or the class definition.
- A docstring should be given a one-line summary followed by a more detailed description.
- Blank spaces should be strategically used to organize the comments but they should not be overused. You can use blank lines to organize code, but don't use them excessively.
In the following sections, let's take a look at more detailed concepts of docStrings.
Docstring styles
A Python docstring has the following slightly different styles:
- NumPy/SciPy
- Epytext
- Restructured
Docstring types
While developing the code, various types of documentation need to be produced, including the following:
- Line-by-line commentary
- Functional or class-level documentation
- Algorithmic details
Let's discuss them, one by one.
Line-by-line commentary
One simple use of a docstring is to use it to create multiline comments, as shown here:
Figure 1.5 – An example of a line-by-line commentary-type docstring
Functional or class-level documentation
A powerful use of a docstring is for functional or class-level documentation. If we place the docstring just after the definition of a function or a class, Python associates the docstring with the function or a class. This is placed in the __doc__ attribute of that particular function or class. We can print that out at runtime by either using the __doc__ attribute or by using the help function, as shown in the following example:
Figure 1.6 – An example of the help function
When using a docstring for documenting classes, the recommended structure is as follows:
- A summary: usually a single line
- First blank line
- Any further explanation regarding the docstring
- Second blank line
An example of using a docstring on the class level is shown here:
Figure 1.7 – An example of a class-level docstring
Algorithmic details
More and more often, Python projects use descriptive or predictive analytics and other complex logic. The details of the algorithm that is used need to be clearly specified with all the assumptions that were made. If an algorithm is implemented as a function, then the best place to write the summary of the logic of the algorithm is before the signature of the function.
