4.8 Documenting your code

Why Documenting Your Code Is So Important

Tip

“Code is more often read than written.”

— Guido van Rossum

Important

Every piece of code you write code has three primary audiences:

your users
your developers
you

Everyone is equally important!

Warning

“Well, Miss Barrett, when that passage was written only God and Robert Browning understood it. Now, only God understands it.”

— Robert Browning

Attention

“It doesn’t matter how good your software is, because if the documentation is not good enough, people will not use it.“

— Daniele Procida

Commenting vs Documenting your code

Comments - to explain a decision in code

Documentation - information about how to install, use, update, debug.

Docstrings

The use of Python documentation strings, sometimes known as “docstrings,” makes it simple to link documentation to specific Python modules, functions, classes, and methods.

It is stated in source code that it is used to document a particular section of code, much like a comment. The docstring should explain what the function does, not how it accomplishes it, unlike traditional source code comments.

More about Docstring Conventions in https://peps.python.org/pep-0257/.

Google Docstrings

More about https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings

def hello_name(username='skillab', email='admin@skillab.com'):
    """Display a simple greeting with 2 parameters.

    Args:
        username (str): The username of your user (default is skillab)
        email (str): The email of your user (default is admin@skillab.com)

    Returns:
        string: a string with information about user and mail
    """
    return f"Hello World {username.upper()} with {email.upper()}!"

reStructuredText Docstrings

More about http://docutils.sourceforge.net/rst.html

def hello_name(username='skillab', email='admin@skillab.com'):
    """Display a simple greeting with 2 parameters.

    :param username: The username of your user (default is skillab)
    :type username: str
    :param email: The email of your user (default is admin@skillab.com)
    :type email: str
    :returns: a string with information about user and mail
    :rtype: string
    """
    return f"Hello World {username.upper()} with {email.upper()}!"