Using docstrings
Docstrings are triple-quoted strings that have special significance within Python. When used, they form the __doc__ attribute of an object. While not using docstrings is fine, and there are many examples of projects that don't have them if you do use them, it is worth looking at PEP 257 to see how to do them right. While violating the guidelines in the PEP won't hurt your code but may make other programmers question you, it will really hurt if you try to use tools such as Docutils, as they expect docstrings to be properly formatted.
How to do it...
- Docstrings are the very first items in a module, function, class, or method; if they are put elsewhere, chances are, tools that won't recognize them as docstrings.
- Docstrings can be single or multi-line, as shown in the following,
docstring_example.py:
def get_pressure():
"""Returns the pressure in the system."""
return sys_press
def calc_press_diff(in, out):
"""Calculates the pressure...
