Writing Effective Functions

The Function's Built-In Explanation

A function can perform the correct task and still be difficult to use if nobody knows what it does. A docstring gives the function an explanation that Python keeps with the function itself. That makes the explanation useful not only to a reader looking at the source code, but also to a running program and to tools that display or generate documentation.

Placing the Documentation

A docstring is a string literal placed immediately after the function definition line. Python can use single quotes, double quotes, or triple quotes for this string. Triple quotes are preferred when the documentation spans multiple lines because they allow multiple lines without requiring escaped newlines.

def greet_user(name):
    """Return a greeting for a user."""
    return "Hello, " + name

Docstrings and Comments

Docstrings and comments both help document code, but Python treats them differently. A comment is text preceded by the hash symbol. Python ignores a comment completely: it is not stored and cannot be accessed by the running program. A docstring is a string literal associated with the function object, so the program can retrieve and display it.

Reading Documentation at Runtime

Because Python stores a function's docstring, a program can retrieve it while running. The special __doc__ attribute contains the function's documentation string. The help() function also uses docstrings to display documentation.

def calculate_total(price, quantity): """Return the total price for a given quantity.""" return price * quantity print(calculate_total.__doc__) help(calculate_total)

Why Documentation Pays Off

A well-written docstring improves code clarity by helping readers understand what a function does. It also helps your future self remember what the function does and what its parameters expect. Because docstrings remain available to tools, they can also provide IDE tooltips and supply material for documentation generators that build reference manuals.

Mistakes Beginners Make

• Writing a comment and expecting it to become function documentation

  Python ignores comments completely. The text is not stored with the function and cannot be retrieved through __doc__ or displayed by help().

  Fix: Use a string literal immediately after the function definition line when the text is intended to be the function's docstring.

• Placing the string somewhere other than immediately after the function definition line

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

  Fix: Put the documentation string before the function's other statements.

• Forgetting that runtime access is available

  The function's docstring can be retrieved during execution through the __doc__ attribute or displayed with help().

  Fix: Use function_name.__doc__ for direct access or help(function_name) for displayed documentation.

Practice and Recall

1. Place a clear string literal immediately after the function definition line.
2. Use triple quotes when the documentation needs multiple lines.
3. Remember that comments are ignored and are not available at runtime.
4. Retrieve documentation with the function's __doc__ attribute or display it with help().
5. Write docstrings that clarify the function's purpose and help explain what its parameters expect.

Key Takeaways

1. A docstring is a documentation string stored as part of a Python function object.
2. A docstring must be placed immediately after the function definition line.
3. Comments begin with a hash symbol and are ignored completely by Python, while docstrings remain accessible.
4. A function's docstring can be retrieved with __doc__ or displayed with help().
5. Docstrings improve clarity and support IDE tooltips and documentation generators.