On Sun, 09 Feb 2014 16:05:59 +0400, bagrat lazaryan 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?
Consider a class with a procedural method, that is, a method that does
something:
class Duck:
def swim(self):
"""Flap feet in a rhythmic manner so as to gracefully move
through water.
"""
Here, we naturally write as if giving instructions to the duck, that is,
using the imperative mood. "Duck, swim."
>From there, it isn't a big step to using the same mood for functions:
def count(haystack, needle):
"""Return the number of needles in haystack."""
Here we are figuratively instructing the function, telling it what to do:
"Function, return the number of needles found in this haystack."
--
Steven
--
https://mail.python.org/mailman/listinfo/python-list
