Code Comments and Readability

Documentation with Two Different Paths

When you read a function, you need to understand what it does without reconstructing every line of its implementation. Python provides two ways to leave explanatory text in source code: comments and docstrings. Both can help a human reader, but Python treats them differently. A comment is ignored, while a docstring becomes part of the function object and remains available while the program runs.

What Survives Source Reading

A comment is a line of text preceded by the hash symbol. Python ignores it completely, so the running program cannot retrieve that comment. A docstring is different: it is a string literal placed immediately after the function definition line. Python stores that documentation as part of the function object.

Writing a Function Docstring

Place the docstring immediately after the function definition line. You can write it with single quotes, double quotes, or triple quotes. Triple quotes are preferred for multi-line documentation because they allow the documentation to span multiple lines without requiring escaped newlines.

def describe_planet(name):
    """Describe what the function does for a given name.

    This text is stored as the function's documentation.
    """
    return "Information about " + name

From Definition to Runtime Access

During execution, Python makes the function available as a function object. Because the documentation string was placed correctly, the function object stores it in the special __doc__ attribute. You can inspect that attribute directly, or ask help() to display documentation based on the docstring.

def convert_temperature(value):
    """Describe a temperature conversion operation."""
    return value

print(convert_temperature.__doc__)
help(convert_temperature)

The first call retrieves the docstring through __doc__. The help() call also uses the function's docstring to display documentation.

Readability Beyond the Source File

A clear docstring helps someone understand what a function does without reading its implementation. It can also help your future self remember what the function does and what its parameters represent. Because docstrings are available to tools, well-written documentation can appear in IDE tooltips and can be extracted by documentation generators to build reference manuals.

Mistakes Beginners Make

• Treating a comment as if the running program can retrieve it.

  Python ignores comments completely; they are not stored or accessible during execution.

  Fix: Use a docstring when the documentation should belong to the function object or be available to help() and documentation tools.

• Putting the string literal somewhere other than immediately after the function definition line.

  A docstring is defined by its placement immediately after the function definition line.

  Fix: Place the documentation string as the first item in the function body.

• Assuming that a docstring and a comment have the same purpose inside Python.

  Both can document code for human readers, but only a docstring is stored as part of the function object and available during execution.

  Fix: Choose a comment for source-only notes and a docstring for documentation that should be retrievable or used by tools.

• Expecting a docstring to be available without placing it in a function's definition.

  The topic here concerns documentation strings stored as part of a function object.

  Fix: Place the string literal immediately after the relevant function definition line.

Practice the Runtime Difference

Key Takeaways

1. A comment begins with # and is ignored completely by Python.
2. A docstring is a string literal placed immediately after a function definition line.
3. Python stores a function's docstring in the function object's __doc__ attribute.
4. The __doc__ attribute and help() make function documentation available during program execution.
5. Clear docstrings improve readability and support IDE tooltips and documentation generators.