26

The error code D401 for pydocstyle reads: First line should be in imperative mood.

I often run into cases where I write a docstring, have this error thrown by my linter, and rewrite it -- but the two docstrings are semantically identical. Why is it important to have imperative mood for docstrings?

Richard
  • 459
  • 1
  • 5
  • 8
  • 4
    The idea is for the first line of the docstring to read like a command, "telling" the function what to do. – chepner Jan 24 '20 at 18:58

7 Answers7

57

From the docstring of check_imperative_mood itself:

  """D401: First line should be in imperative mood: 'Do', not 'Does'.

   [Docstring] 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 ...".

(We'll ignore the irony that this docstring itself would fail the test.)

chepner
  • 497,756
  • 71
  • 530
  • 681
15

It is more important to have a consistent style within a project or in a company.

The whole idea comes from the PEP-257, which says

The docstring is a phrase ending in a period. 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 …”.

But for example the Google Python Style Guide states the total opposite of this:

The docstring should be descriptive-style ("""Fetches rows from a Bigtable.""") rather than imperative-style ("""Fetch rows from a Bigtable.""").

UPDATE (2023): The Google style guide was changed since then. Now it allows both styles without explicit preference:

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.

Also worth to mention that both the Oracle Java style guide and the Microsoft .NET guides prefer the descriptive style.

Use 3rd person (descriptive) not 2nd person (prescriptive).

The description is in 3rd person declarative rather than 2nd person imperative.

Gets the label. (preferred)

Get the label. (avoid)

So it looks like this preference of imperative style is Python-specific.

csadam
  • 401
  • 1
  • 5
  • 15
13

Consider the following example candidate for a docstring:

Make a row from a given bit string or with the given number of columns.

In English, this is a complete, grammatical sentence that begins with a capital letter and ends with a period. It's a sentence because it has a subject (implicitly, "you"), an object, "row," and a predicate (verb), "make."

Now consider an alternative:

Makes a row from a given bit string or with the given number of columns.

In English, this is ungrammatical. It is an adjectival phrase, therefore it should not begin with a capital letter and should not end with a period. Let's fix that problem:

makes a row from a given bit string or with the given number of columns

As an adjectival phrase, its antecedent --- its target --- is not explicit. Of course, we know it's the item being "docstringed," but, grammatically, it's dangling. That's a problem. Aesthetically, it's ugly, and that's another problem. So we fixed one problem and added two more.

For people who care about clear, anambiguous communication in grammatical English, the first proposal is clearly superior. I will guess that's the reason the Pythonistas chose the first proposal. In summary, "Docstrings shall be complete, grammatical sentences, specifically in the imperative mood."

Reb.Cabin
  • 5,426
  • 3
  • 35
  • 64
  • 2
    You can always put a noun such as `[func_name]` at the beginning to turn that one-line summary into a sentence. Example: *`make_row` makes a row*. – Mateen Ulhaq Apr 03 '21 at 04:27
  • 4
    That is a complete and meaningful sentence. Conversely, *"Make a row."* is a complete sentence... that does not mean what it states. Are we commanding the reader to make a row? What other interpretation could there be when a reader is confronted with such a blatantly authoritative and demanding tone? If you excuse me, I am now off to make a row... – Mateen Ulhaq Apr 03 '21 at 04:33
  • 2
    @MateenUlhaq ambiguity lurks around every corner and behind every door in English, and, I daresay, any other human language. It's a good thing, too, lest humor, poetry, allusion, and metaphor be impossible (how's that for "subjunctive!"). But ambiguity kills computers and mathematics and science and engineering, so we fight it, and often lose the battle whilst winning the war? Your pun on "row" is appreciated :) – Reb.Cabin Apr 16 '21 at 00:36
9

Why is it important? Because that's the explicit convention for Python docstrings, as detailed in PEP 257. There's nothing particularly special about it - it doesn't seem obvious to me that one of "Multiplies two integers and returns the product" and "Multiply two integers and return the product" is clearly better than the other. But it is explicitly specified in the documentation.

Mark Snyder
  • 1,635
  • 3
  • 12
9

It is not complete to just say it is about a convention or a consistency (otherwise, the follow-up question would be, "consistent with what?").

It is actually an explicit requirement from - albeit buried down deep in - the canonical PEP 257 Docstring Conventions. Quoted below:

def kos_root():
    """Return the pathname of the KOS root directory."""
    ...

Notes:

  • The docstring is a phrase ending in a period. 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 ...".

That pydocstyle docstring was actually quoted from PEP 257 paragraph above.

RayLuo
  • 17,257
  • 6
  • 88
  • 73
3

For consistency. It might stem from the fact that the commit messages git automatically creates, like for merge commits, also uses the imperative mood.

Jorn Vanloofsvelt
  • 356
  • 2
  • 11
1

I find the grammatical argument compelling.

I use the imperative style for names and docstrings. In my experience, the imperative style works better in review. People are more likely to comment on an obvious untruth when "what" of the docstring disagrees with "how" of the code:

    def _update_calories(meal):
        return sum(item.calories for item in meal)  # where is the update?

I use the descriptive style for some inline comments when I want to highlight an unexpected behaviour. In my experience, people tend to read descriptive phrases as authoritative:

    def _update_calories(meal):
        meal.calories = sum(item.calories for item in meal)
        return meal.calories

    # warning: changes pizza.calories, easy to miss side-effect
    calories = _update_calories(pizza)
dhill
  • 3,327
  • 2
  • 19
  • 18