Comments and Docstrings

14. Comments and Docstrings#

Comments are used to explain the code. The interpreter doesn’t execute the comments. There are 3 types of comments in Python:

  • Single Line

  • In-Line

  • Multi Line

14.1. Single Line#

Single line comments are written in a single line. Single line comments start with #

# Here's a single line comment

14.2. In-Line#

In-Line comments are written beside the code.

print("Hello")  # Here's a In-Line comment

14.3. Multi Line#

Sometimes we need to write a huge explanation using comments, in those cases we do use multi-line comments. multiline comments are enclosed in """ """ or ''' '''

"""
Here's a 
multiline comment.
"""

14.4. Docstrings#

Docstrings are specific type of comments that are stored as a attribute to the module, class, method or function.

Docstrings are written similar to the multi-line comments using """ """ or ''' ''', the only difference would be they are written exactly at the start(first statement) of the module, class, method or function.

Docstrings can be programmatically accessed using the __doc__ method or through the built-in function help. Let’s give a try 😎.

def double_the_value(value: int):
    """Doubles the integer value passed to the function and returns it."""
    return value * 2

14.4.1. Using help#

help function provides the docstrings as well as the information about the module, class, method or function.

help(double_the_value)

Help on function double_the_value in module __main__:

double_the_value(value: int)
    Doubles the integer value passed to the function and returns it.

14.4.2. Using __doc__#

print(double_the_value.__doc__)

Doubles the integer value passed to the function and returns it.

Can we use the single line comments instead of multi-line docstrings 🤔? Let’s try this as well.

def test_single_line_comment_as_docstring():
    # This is a single-line comment
    pass

print(test_single_line_comment_as_docstring.__doc__)

None

We can see that None is printed, which explains that we can’t use single-line comments as docstrings 🙂

14.5. Docstrings for documentation of code.#

PEP-257 defines two types of docstrings.

  • One-Line docstring

  • Multi-Line docstring

14.5.1. One-Line docstring#

One-line docstrings are suited for short and simple Modules, classes, methods or functions.

def one_line_docstring():
    """This is a one-line docstring"""
    pass

14.5.2. Multi-Line docstring#

Multi-line docstrings are suited for long, complex Modules, classes, methods or functions

def multi_line_docstring(arg1: int, arg2: str) -> None:
    """
    This is a multi-line docstring.

    Arguments:
      arg1 (int): Argument 1 is an integer.
      arg2 (str): Argument 2 is a string.
    """
    pass

14.6. Styles of docstrings#

There are multiple styles of writing docstrings such as reStructuredText, Google Python Style Guide, Numpy style.

We could use any of the above docstrings style as long as we stay consistent.

Sphinx is a tool that generated beautiful HTML based documentation 📜 from the docstrings we provide in our code. reStructuredText is the default style, for other styles like Google Python style, numpy we could use plugins like Napoleon.

Sphinx also provides various templates we can choose from to create the HTML documentation out of it. 😎♥️

14.6.1. A meme on Documentation 😂#

Documentation

It’s always good and professional to have our code documented 🙂.

Contents