Well-defined documentation

Well-defined and clear documentation is as important as writing a generalized and independent module with the Python coding guidelines. Without clear documentation, the module will not increase the interest of developers to reuse with convenience. But as programmers, we put more focus on the code than the documentation. Writing a few lines of documentation can make 100 lines of our code more usable and maintainable.

We will provide a couple of good examples of documentation from a module point of view by using our mycalculator.py module example:

"""mycalculator.py

This module provides functions for add and subtract of two numbers"""

def add(x, y):

""" This function adds two numbers.

usage: add (3, 4) """

return x + y

def subtract(x, y):

""" This function subtracts two numbers

usage: subtract (17, 8) """

return x - y

In Python, it is important to remember the following:

• We can use three quote characters to mark a string that goes across more than one line of the Python source file.

• Triple-quoted strings are used at the start of a module, and then this string is used as the documentation for the module as a whole.

• If any function starts with a triple-quoted string, then this string is used as documentation for that function.

As a general conclusion, we can make as many modules as we want by writing hundreds of lines of code, but it takes more than writing code to make a reusable module, including generalization, coding style, and most importantly, documentation.