On Python

Code Documentation: An Ignored Skill

Vahid's photo
Vahid
·

1 min read

I have taken quite a few courses on Programming in general and Python in particular. One of the things that I have noticed is the lack of a section how to document your code by providing good documentation.

Python comes with the PyDoc module built-in, so in order to create an html report or documentation for your modules you just need to provide good docstrings (comments enclosed in a pair of three quotes) to explain what the code does.

def adding(a, b):
    """
    Params: two numbers as integer or float
    Return: the result of adding the two given numbers
    """
    return a+b

The above code documents what it takes and what it returns.

Now, in order to automatically generate an html documentation page, we just need to open the terminal in the same directory of our python code:

# assuming the name of the file is main.py
python -m pydoc -w main

The above code creates an html page called main.html in the same directory.

There are other ways of doing the same thing. You can refer to a more detailed explanation of how to use pydoc for generating python documentation HERE.

pydoc