Documentation

[TriplEight]

The handbook needs a good section on the code documentation. From the top of my head I could only come up with a bad and improved example, but it seems a bit bulky to fit into a handbook.

Well-documented code should shortcut right to the conclusion, instead of reading and interpreting a chunk of code. It should describe all ins, outs and design decisions taken in the piece of code, making it not necessary to read the potentially not very important at the moment implementation. At the same time, it should be concise and free of unnecessary details.

Example of a Bad Code Documentation:

# Function: calculate
# Parameters: x, y
# Returns: result
# Description: This function calculates the sum of two numbers.
def calculate(x, y):
    # add the numbers
    result = x + y
    # return the result
    return result

Explanation:

• The function name "calculate" is not descriptive.
• The parameter names "x" and "y" are not descriptive, making it unclear what kind of values they represent.
• The return value "result" does not indicate what it represents or its purpose.
• The description of the function is redundant and does not provide any additional meaningful information.
• There is no information about possible errors, edge cases, or any other relevant details.

Improved Code Documentation:

def sum_two_numbers(num1, num2):
    """
    Calculate the sum of two numbers.

    Args:
        num1 (int): The first number.
        num2 (int): The second number.

    Returns:
        int: The sum of num1 and num2.

    Raises:
        ValueError: If either num1 or num2 is not a valid integer.

    Example:
        >>> sum_two_numbers(2, 3)
        5
    """
    try:
        result = int(num1) + int(num2)
        return result
    except ValueError:
        raise ValueError("Both arguments must be valid integers.")

Explanation:

• The function name "sum_two_numbers" clearly conveys the purpose of the function.
• The parameter names "num1" and "num2" are more descriptive and indicate that they represent numbers.
• The return value is explicitly defined as an integer and its purpose is clear.
• The documentation includes a description, specifying what the function does.
• The "Raises" section mentions a specific error that can occur and provides a helpful error message.
• An example is provided to demonstrate how to use the function and what output to expect.

In the improved example, the code documentation is more informative, providing better context, details, and examples. It helps developers understand the purpose, usage, and potential errors of the function, promoting better code comprehension and usage.

[zakirullin]

@TriplEight Hi there, thanks for your participation!

    Args:
        num1 (int): The first number.
        num2 (int): The second number.
    Returns:
        int: The sum of num1 and num2.

I think these documentation lines should be easily replaced with just self-documenting code.

Programs must be written for people to read, and only incidentally for machines to execute.

Code Tells You How, Comments Tell You Why.

The general rule for code comments is that you should write WHY it is done the way it is done, not HOW it is done.
We should comment all not-so-obvious, tricky parts of our code.
We should write some concise top-level module comments, so a reader could quickly understand its purpose without diving deep.

We can indeed reduce cognitive load greatly by writing good comments (like top-level module comments), but to come up with really good examples we need to brainstorm more.

@TriplEight I like your initial idea, we can build on it and create a good section about documentation.

[TriplEight]

Code Tells You How, Comments Tell You Why.

This is one of the approaches. Another one is that the code should implement the (low-level) spec. And the parts of the implementation should link to the corresponding parts of spec. In the other words, every block of code should be explained, so that it's not needed to read the code when there are such explanations. This drastically improves searching the part one needs to change as well as the onboarding of the newcomers.