imperative mood in docstrings
roy at panix.com
Sun Feb 9 17:52:15 CET 2014
In article <mailman.6584.1391950328.18130.python-list at python.org>,
bagrat lazaryan <bagratte at live.com> wrote:
> pep 257 -- docstring conventions, as well as a myriad of books and other
> resources, recommend documenting a function's or method's effect as a command
> ("do this", "return that"), not as a description ("does this", "returns
> that"). what's the logic behind this recommendation?
Methods are verbs, and should be described as such. If I had:
"Plummet to the ground."
I'm defining the action the verb performs. If, on the other hand, I had:
"Plummets to the ground"
I'm no longer describing the action of flying, I'm describing what the
sheep does when it attempts to perform that action.
More information about the Python-list