writing-docstrings

Writing Docstrings

Overview

In a repo using repo-hygiene, docstrings on functions/classes and headers on source files are required. This OVERRIDES the default "no comments unless WHY is non-obvious" stance. The override exists because docstrings ARE the API contract — a future reader (human or agent) shouldn't have to read the body to know what to expect.

Core principle: A docstring earns its place by telling the reader something the signature does NOT tell them.

When To Use

• Writing a new function, method, or class
• Modifying a function's signature, return type, or contract
• Creating a new source file (write a header)
• Reviewing your own code before commit

What Earns a Docstring Its Place

A good docstring covers what the signature CAN'T:

1. Contract — one-sentence promise, present tense
2. Parameters — only those whose meaning isn't obvious from type/name
3. Returns — only if non-obvious from the return type
4. Raises / errors — failure modes the caller must handle
5. Caveats — non-obvious behavior, side effects, performance, thread-safety

Skip anything the signature already conveys. The goal is information, not ceremony.

Before / After

❌ Restates the signature (worthless):

def parse_date(raw: str) -> datetime:
    """Parse a string and return a datetime."""
    return datetime.strptime(raw, "%Y-%m-%d")

❌ Empty ceremony:

def parse_date(raw: str) -> datetime:
    """
    :param raw: the raw string
    :returns: the parsed datetime
    """

✅ Pins what the signature can't:

def parse_date(raw: str) -> datetime:
    """Parse a YYYY-MM-DD date. Raises ValueError on any other format."""
    return datetime.strptime(raw, "%Y-%m-%d")

File Headers

Every source file gets a header explaining its role. A header that just paraphrases the filename is worse than no header.

❌ Paraphrases filename:

"""user_repository.py — the user repository."""