Docstring Style Guidelines

[stevenjackson121]

Documentation request: Clarify Docstring Style Guidelines

What documentation needs to change?

contributing.md and/or doc/contributing_guide should specify the preferred docstring format.

Where is it located?

contributing.md and/or doc/contributing_guide

What is wrong with it? How can it be improved?

There are no standards for docstrings. This leads to inconsistency in contributed code, which wastes mental effort for users who read the documentation, and simply looks unprofessional. The differences between two similar functions' docstrings should be limited to the functional differences between the functions, in order to allow users to understand the important differences as quickly and easily as possible.

Using inconsistent voices/tenses/capitalization/punctuation to say the same thing in different ways raises the barrier to entry for non-native English speakers especially, who are less likely to immediately understand the equivalence of these variations and more likely to spend time trying to figure out if the differences are meaningful.

A style guide would improve consistency for docstrings. Consistent docstrings would help the project appear more polished and professional, as well as communicate more clearly with users.

Recommendation

Docstrings should follow the following conventions, and these conventions should be added to the appropriate documentation listed above:

1. Docstrings should be capitalized.
2. Docstrings should end with end with punctuation: ".", "?", or "!".
3. Docstrings should use imperative style: "Return x" instead of "Returns x"
4. Multi-line docstrings must be a summary, followed by a blank line, followed by a full description.
5. Docstring should not be longer than 80 lines.

Rationale

These rules are consistent with the formatting of Python's own docstrings, PEP 287 (which is referenced by PEP 8) and also consistent with Google's Style Guide which is another common standard.

The exact specification matters less than having some standard in place, so I'm open to tweaks for any/all of these individual rules.

[cspotcode]

Your recommendation looks good to me.

When reviewing PRs, I doubt I'll ever count lines in a docstring to check if it's less than 80 lines. But the others are easy to verify.

It will be helpful to add screenshots of a well-written docstring to show how it benefits users.

• screenshot of a well-written docstring rendered on the website rendered on the website
• screenshot of a well-written docstring in a VSCode / PyCharm tooltips

[stevenjackson121]

Sorry I meant the summary line should be less than 80 characters long, I don't think there's any restriction on number of lines. I'll look into getting screenshots tomorrow.

[pushfoo]

If we don't already have linting for docstrings enabled:

1. We should add or enable it
2. It should probably be done as a follow-up to this issue + PR(s)

[cspotcode]

Good idea, linking to some Discord chat about docstring linting:

https://discord.com/channels/458662222697070613/705076586986078350/1138947337998315560
Talking about docs coverage: how to verify that everything is appearing on the website.

https://discord.com/channels/458662222697070613/705076586986078350/1138951296775364669
Talking about validate that docstring "Parameters:" and "Keyword Arguments:" tables are kept in sync with the code.
E.g. if a function's parameter is rewritten from foo to bar but the docstring still refers to parameter foo, linter can flag as a mistake

[cspotcode]

Another item in the list:

When documenting a @property, only the getter's docstring will appear in sphinx, not setter. If setter allows different types, for example when setting Color from a 3-tuple, this must be described in the getter docstring.