PEP 257: Allow docstrings to be descriptive/indicative style

PEPs
1

CLOSED

Maybe it’s time to update this convention from 2001? I think we should have a similar approach to that of Google’s style guide and be more lenient. (see below)

It may not always be grammatically correct but it is much more natural as most people describe things indicatively and not imperatively.

In PEP 257:

It prescribes the function or method’s effect as a command (“Do this”, “Return that”), not as a description; e.g. don’t write “Returns the pathname …”.

However in the newer (updated in 2023) Google Python Style guide:

The docstring may be descriptive-style ("""Fetches rows from a Bigtable.""") or imperative-style ("""Fetch rows from a Bigtable."""), but the style should be consistent within a file.

Previous Python discussion:

Other conventions:

Other discussions:
2

First off: Why? Just because advice is old doesn’t mean it’s wrong. What is the advantage of being sloppier?

Secondly: PEP 257 defines conventions, not absolutes. It is not a straitjacket for you to have to follow, unless your organization/project has chosen to mandate it. Discuss with your team as to what you want to be sloppier about and come to an agreement; you can do that without any change to the document itself.

The existing style is simple, consistent, and matches expectations. I personally see no reason to use “Returns” rather than “Return”. A function is a thing that DOES something, so describe what it DOES. It’s the same with commit messages - they read much more cleanly if you are consistent with your style and always write them imperatively. There’s no benefit in being inconsistent with them.

4 Likes
3

Hmm, I’m skimming the discussion, but this seems to me to be wholly in agreement with PEP 257 and git commit advice, advocating for “Return” and not “Returns”. You’re linking to a merged PR that removed the “s” for consistency with the rest of the codebase. So, this is very definitely in the “imperative” camp.

4

Descriptive docstrings can often feel more intuitive and readable, especially for newcomers. It’s much more natural language.

I did not say it is wrong – I’m proposing the PEP is made more flexible like other style guides, not to replace an existing convention.

A function is a thing that DOES something, so describe what it DOES.

The descriptive still achieves this.

5

Got evidence to support that, or is it an assertion of your preference? Preferences are fine, but they are preferences, not absolutes.

6

Docstrings are facts, not commands. It is therefore more natural for them to be in the indicative (factual) mood rather than a command.

When describing something one would not say:

Make spam from ham.

One would say:

Makes spam from ham.

7

I agree with ChrisA, especially noting that (as with PEP 8), these are suggested conventions (per the title!). From the PEP:

If you violate these conventions, the worst you’ll get is some dirty looks.

Seconded.

Docstrings are a special kind of prose, where clarity of expression is very important. We should neither adopt worse standards of English nor worse grammar. Most importantly, and to reinforce the point, anyone is free to choose different conventions for their own projects. The Google style-guide is one such different convention, as is Numpydoc, and these can coexist with PEP 257.

A

1 Like
8

You just explained the distinction between imperative and descriptive styles. Yes. When DESCRIBING something you would say “Makes”, although you don’t have a full sentence. The imperative mood is COMMANDING, and is what you would have in a recipe book. “Collect ingredients. Sift the flour and sugar. Fold until folded.” Neither is inherently better than the other, but they have their places, and if you worded a recipe book as “This step makes spam from ham”, it would be confusing.

9

Just to chime in my useless two cents.

I’ve always found it weird that convention is imperative mood. The cookbook example doesn’t hold as well when I compare it to code. The cookbook is commanding the reader to do something, that makes sense. Who is the docstring commanding? Certainly not the person reading it. Is it commanding the code? That doesn’t jibe with me either. Code cannot be commanded. It’s the code.

Anyway, I do wish linters had the option to ensure docs were “not imperative.” To each their own.

2 Likes
10

Code is a command to the computer. A patch [1] is a command to the file system (or repository).

A function can also be seen as other things - especially a pure function, like math.sin - but it is valid to see it as a set of commands to the computer (or to the interpreter, if you prefer).

  1. a commit can be seen as a patch with associated metadata ↩︎

1 Like
11

The rule given in How to Write a Git Commit Message for imperative mood for commit message summaries is the following:

Writing this way can be a little awkward at first. We’re more used to speaking in the indicative mood, which is all about reporting facts. […] To remove any confusion, here’s a simple rule to get it right every time.

A properly formed Git commit subject line should always be able to complete the following sentence:

  • If applied, this commit will your subject line here

The same rule can be used for docstrings: “when ran, this function will your docstring summary here”.

That is, instead of “this function your docstring summary here”.

6 Likes
12

Please end this religious war now. (Both of you!)

We’re not going to change this.

If it continues I will get a moderator.

5 Likes
13

Closed as the OP edited their opening post to say “CLOSED”.