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/
_______________________________________________
Tutor maillist - Tutor@python.org
To unsubscribe or change subscription options:
http://mail.python.org/mailman/listinfo/tutor
