As with naming, docstrings might seem to be a minor issue – but they are not. Always add a docstring to your code; it will double your productivity! Also, it will help you to keep good relationships with your colleagues and clients.

As we mentioned before, docstrings are short explanation texts bound to specific module (.py file), function, or class. All you need is to write it as a string at the beginning of the corresponding scope – beginning of the file, function, or class. At the execution time, those strings are stored as a __docs__ variable. What's even more important is the fact that all coding environments, including VS Code and Jupyter, understand docstrings and how to handle them.

As we mentioned previously, in Jupyter, adding a question mark before or after any class, module, or function, will print out corresponding documentation. This will work for any function – including the ones you declared. The following is an example of a function declaration that includes a docstring:

def myfunction(a, b):
     '''this is my favorite function!

     it uses arguments:
     a: argument a
     b: argument b
     '''
     return a + b

Once the function is declared (or imported), we can pull the documentation by using the question mark – similar to how we approached the print function before:

>>> myfunction

Signature: myfunction(a, b)
Docstring:
this is my favorite function!
it uses arguments:
a: argument a
b: argument b
File: ~/<ipython-input-2-a0cabd3ba678>
Type: function

VS Code will do even more – it will show docstrings in a tooltip while you're typing. 

But that is not the only thing you can use your docstrings for! Using the sphynx package, you can generate full stack documentation such as a static website, PDF, or an EPUB electronic book, which extracts all the information from the docstrings. If you are wondering why there are so many similar cookie-cutter documentation websites around, that's why! An enhanced version even encourages you to add example code within the docstring – and there are packages that will test and validate this code-within-the-docstrings!

There is no standard format for the docstrings. Instead, there are a few style formatting conventions used in different companies and groups. Among the most popular ones are the REST, Google Style, and numpydoc styles. For example, here is an example of a docstring defined according to Google Style:

"""
This is an example of Google style.

Args: parameter1: This is our first parameter.
      parameter2: This is our second parameter.

Returns:
    This is a description of what is returned.

Raises:
    KeyError: Raises an exception.
"""

It does not really matter which style to use. If you like restructured text, use REST. If you don't, use the Google Style or NumPy style. There are plugins that help to generate docstring templates from your function arguments on the fly – they save some time. Further time can be saved using type annotations.