Why is imperative mood important for docstrings?
Question:
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?
Answers:
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.)
For consistency. It might stem from the fact that the commit messages git automatically creates, like for merge commits, also uses the imperative mood.
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.
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.”
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.
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.""").
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.
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)
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?
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.)
For consistency. It might stem from the fact that the commit messages git automatically creates, like for merge commits, also uses the imperative mood.
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.
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.”
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.
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.""").
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.
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)