[Tutor] Prescriptive vs descriptive docstring

[Alan Gauld]

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
> function/method,

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 
definitive explanation.

-- 
Alan G
Author of the Learn to Program web site
http://www.alan-g.me.uk/