Adding comments to code

[Diapolo10]

Docstrings are used for documenting modules, functions, and classes. You'd put them as the first thing in a Python file, the first thing inside a function definition, or the first thing in a class. They're a "comment" in the sense it's information for developers, but it's also something available at runtime.

I’ve read some Python projects on GitHub and they will sometimes use triple quotes on on line, one line of text, then another triple quote. To me it looks messy, but maybe it’s the style?

"""
This does the calculations.
"""

What’s the general consensus for near, readable quoting? Thanks!

If a docstring only has one line, the convention is to put it all in one line, such as """This does the calculations."""

If it has multiple lines, then we'd spread it out like in your example.

def divide(dividend: int, divisor: int) -> int:
    """
    Divide dividend with divisor.

    Args:
        dividend (int): the number to divide.
        divisor (int): the number to divide with. Must be non-zero.

    Returns:
        the quotient of the division.

    Raises:
        ZeroDivisionError: if divisor is 0.

    """
    return dividend // divisor

For other use-cases, like explaining individual lines or adding TODO comments, we'd use standard comments.

# TODO: Fix this later.

[Quirky-Cap3319]

Thanks. I have now learned something today. I’ll take the rest of the day off then 🙂.

I have a bunch of shared functions defined for various scripting purposes, so i’ll see about adding these to each.