pythondoc-authoring

Authoring a Python docstring

This skill governs what a docstring says and in what order. Wording, tone, sentence length, and dialect belong to english-developer-style: load it too, and defer to it on the prose. The two compose: this skill picks the slots; that one writes the sentences.

Two facts about Python change the job at the root, and both come back in later sections.

A docstring is a runtime object, not source text. It is __doc__: help() renders it, doctest executes the examples in it, a CLI framework can print it as --help, and python -OO deletes it. Every one of those is a surface an edit reaches.

No formatter owns its prose. black and ruff format re-indent a docstring's body and strip its trailing whitespace, but they never rewrap it (measured on ruff 0.14). You place the line breaks, and E501 counts them.

Conventions carried in from another language's doc comments go wrong in three places, so do not translate them in your head. The summary is one physical line whose mood the project picks, not a first sentence fixed in the third person (§3). References have no syntax of their own, so the form depends on the renderer and nothing checks it by default (§5). The section headings belong to a dialect the project has already chosen, not to the language (§6).

1. The correction that matters most

"Document the why, not the what" is half wrong for a docstring, and the wrong half does the damage.

An inline # comment documents the why; it sits next to code the reader can already see. A docstring documents the contract: what a caller may rely on, what an implementer must guarantee, what holds before and after. That is a what at the level of a promise, not a restatement of the code.

The failure mode is therefore not "explains what the code does". It is one of these:

• Narrating the implementation. Loops over the rows and adds each to the index. The body already states it, and the docstring becomes false on the next refactor.
• Justifying the code's existence. This helper centralizes the retry logic every client copied. That belongs in the commit message and the pull request description. A docstring's reader has to use or fix the thing, not decide whether to merge it.
• Restating the annotations, which is Python's own. Args: timeout (float): the timeout in seconds. on def fetch(timeout: float) carries one fact, the unit, and pays for it with a line the reader has to sift. The annotations are the signature; §6 says what a parameter line has to add before it earns its place.