[Tutor] Prescriptive vs descriptive docstring
alan.gauld at btinternet.com
Fri May 11 09:23:32 CEST 2012
On 11/05/12 04:41, Kal Sze wrote:
> PEP 257 says that docstrings should be written in a prescriptive way
> (i.e. using the imperative mood) instead of a descriptive way
> (indicative mood). This seems like a rather odd recommendation. Since
> the docstring is supposed to tell the programmer *how* to use a
This might be down to interpretation of the terms.
To me it means the docstring should tell, or instruct, the user how to
use the function. It should not describe what the function does or how
it does it (the internal logic).
> command? Who are you "commanding" when what you really want is to learn
> what the function/method does?
It's commanding (or instructing) the user on how to use the function.
You don't need to know what its doing internally, only how to use it.
It tells me that if I push these things in, it will give me that thing back.
But that's just how I interpret it. Somebody else may have a more
Author of the Learn to Program web site
More information about the Tutor