Comments and Docstrings in Python

Code is read far more often than it is written. Comments explain why code does something non-obvious, and docstrings document what modules, functions and classes do — and, unlike comments, they are available at runtime through help() and used by IDEs and documentation generators.

This lesson covers single-line and "multi-line" comments, docstring conventions for functions and classes, and how to write comments that help rather than clutter.

Comments

A comment starts with # and runs to the end of the line; Python ignores it. Python has no special multi-line comment syntax — use several # lines. (A bare triple-quoted string is sometimes used, but it is really a string expression, not a comment.) Inline comments should be separated from code by at least two spaces.

Docstrings

A docstring is a string literal that is the first statement of a module, function, class or method. It is stored in the object's __doc__ attribute and shown by help(). Use triple double quotes. The first line is a short summary; longer docstrings describe arguments, return values and exceptions — common styles are Google style and NumPy style.

Writing Good Comments

Explain intent, business rules and surprising decisions ("Tax is rounded per item, as required by GST rules"), not what the code obviously does ("increment i"). Keep comments updated — a wrong comment is worse than none. Prefer clear names and small functions over explaining unclear code with comments.

Examples

# Calculate the final price after discount and GST
price = 1000
discount = 0.10      # 10% festival discount

# GST is applied after the discount,
# as required on the invoice.
final_price = price * (1 - discount) * 1.18
print(round(final_price, 2))

1062.0

def bmi(weight_kg, height_m):
    """Return the body-mass index.

    Args:
        weight_kg: Weight in kilograms.
        height_m: Height in metres.

    Returns:
        The BMI rounded to one decimal place.
    """
    return round(weight_kg / height_m ** 2, 1)


class Student:
    """A learner enrolled on the Webnest platform."""


print(bmi(68, 1.75))
print(bmi.__doc__.splitlines()[0])
print(Student.__doc__)

22.2
Return the body-mass index.
A learner enrolled on the Webnest platform.