Comments

We use comments to explain our code. Comments are ignored by Python, but are useful to ourselves and others reading or using our code.

We will generally encounter two kinds of comments:

1. Block and inline comments
2. Docstrings

The former are comments starting with a #, included in the code itself. Everything after the # on the line will not be executed by Python.

The second kind of comment, docstrings, are indicated by pairs of triple single or double quotes, can be used as “multi-line” comments, e.g.

"""
Ada Lovelace
CS 150 Lab 1
Creativity:
- defined dollars_to_euros() function that calls my euros_to_dollars() function
- added new function analytical_engine()
"""

Docstrings are a formal part of the Python specification and provide a structured mechanism for documenting functions, classes, and other entities in your Python code. To define a docstring we use the three double quotes format, i.e., """. If the function is very simple we can use a single line. If not, we want to document the purpose, parameters, return value and any exceptions.

def double_it(x):
    """
    Doubles input.
    
    Args:
    	x: value to be doubled
    
    Returns:
    	Doubled value
    """
    return x * 2

What is the difference between inline comments and docstrings? The intended audience.

An inline comment is intended for those who are reading your code and need to understand what you were trying to do.

A docstring is intended for those who want to use your function, so it should describe what the function does, its parameters, and what (if any) return value it produces.

The docstring informs the output of the help functionality. As you saw in the reading you can obtain the documentation for functions, etc., with help. For example:

>>> help(print)
Help on built-in function print in module builtins:

print(...)
    print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
    
    Prints the values to a stream, or to sys.stdout by default.
    Optional keyword arguments:
    file:  a file-like object (stream); defaults to the current sys.stdout.
    sep:   string inserted between values, default a space.
    end:   string appended after the last value, default a newline.
    flush: whether to forcibly flush the stream.

The docstrings we provide as part of our own function definitions produce documentation using help as well, e.g.,

>>> help(double_it)
Help on function double_it in module __main__:

double_it(x)
    Doubles input.
    
    Args:
    	x: value to be doubled
    
    Returns:
    	Doubled value

In every lab we will ask you to comment your code. The purpose of the comments is to describe what your code is doing, not to describe the code itself; you can assume the reader knows Python. But the reader doesn’t necessarily know what you are trying to do.

Good comments are important for readability and maintainability of your code. Among those most likely to read your code in the future is you, after you forgot all about it, so think of good commenting as being kind to future you as well as other readers.