All Python code should have docstrings at the module, class and method level. Not every single method requires a docstring. Some method names are really well chosen, and little more needs to be said. Most times, however, documentation is essential for clarity.
Python documentation is often written using the reStructuredText (RST) markup.
Throughout the code examples in the book, however, we'll omit docstrings. The omission keeps the book to a reasonable size. This gap has the disadvantage of making docstrings seem optional. They're emphatically not optional.
This point is so important, we'll emphasize it again: docstrings are essential.
The docstring material is used three ways by Python:
- The internal help() function displays the docstrings.
- The doctest tool can find examples in docstrings and run them as test cases...
