RE: imperative mood in docstrings
thank you all! bagratte -- https://mail.python.org/mailman/listinfo/python-list
imperative mood in docstrings
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? bagratte -- https://mail.python.org/mailman/listinfo/python-list
Re: imperative mood in docstrings
In article mailman.6584.1391950328.18130.python-l...@python.org, bagrat lazaryan bagra...@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? bagratte Methods are verbs, and should be described as such. If I had: class Sheep: def fly(self): Plummet to the ground. I'm defining the action the verb performs. If, on the other hand, I had: class Sheep: def fly(self): 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. -- https://mail.python.org/mailman/listinfo/python-list
Re: imperative mood in docstrings
On 09/02/2014 12:05, 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? bagratte I can't really answer your question as I don't understand why docstrings should get moody, or did you mean mode? :) -- My fellow Pythonistas, ask not what our language can do for you, ask what you can do for our language. Mark Lawrence --- This email is free from viruses and malware because avast! Antivirus protection is active. http://www.avast.com -- https://mail.python.org/mailman/listinfo/python-list
Re: imperative mood in docstrings
Mark Lawrence writes: On 09/02/2014 12:05, 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? I can't really answer your question as I don't understand why docstrings should get moody, or did you mean mode? :) http://en.wikipedia.org/wiki/Grammatical_mood -- https://mail.python.org/mailman/listinfo/python-list
Re: imperative mood in docstrings
On Sun, Feb 9, 2014 at 5:52 PM, Roy Smith r...@panix.com wrote: In article mailman.6584.1391950328.18130.python-l...@python.org, bagrat lazaryan bagra...@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? bagratte Methods are verbs, and should be described as such. If I had: class Sheep: def fly(self): Plummet to the ground. I'm defining the action the verb performs. If, on the other hand, I had: class Sheep: def fly(self): 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. This can also be seen with a (monolingual) dictionary. For example: https://www.google.com/search?q=define+fly (that’s actually from the New Oxford American Dictionary): fly, verb: 1. move through the air under control. 2. move or be hurled quickly through the air. Those could be valid docstrings (if sheep could fly, of course…) — so, in other words, act as if you were writing a dictionary and not Python code. -- Chris “Kwpolska” Warrick http://kwpolska.tk PGP: 5EAAEA16 stop html mail | always bottom-post | only UTF-8 makes sense -- https://mail.python.org/mailman/listinfo/python-list
Re: imperative mood in docstrings
On 02/09/2014 08:52 AM, Roy Smith wrote: In article mailman.6584.1391950328.18130.python-l...@python.org, bagrat lazaryan bagra...@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? bagratte Methods are verbs, and should be described as such. If I had: class Sheep: def fly(self): Plummet to the ground. I'm defining the action the verb performs. If, on the other hand, I had: Shouldn't that be: class Pig: def fly(self): Soar gracefully through the air if a hot place is very cold. if hell is frozen: self.sprout_wings() self.altitude += 10 self.velocity += 25 else: self.splat() ;) -- ~Ethan~ -- https://mail.python.org/mailman/listinfo/python-list
Re: imperative mood in docstrings
On 2/9/2014 7:05 AM, 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? The imperative is directed at the Python interpreter. It says what a call instructs the interpreter to do. -- Terry Jan Reedy -- https://mail.python.org/mailman/listinfo/python-list
Re: imperative mood in docstrings
On Mon, Feb 10, 2014 at 4:53 AM, Ethan Furman et...@stoneleaf.us wrote: Shouldn't that be: class Pig: def fly(self): Soar gracefully through the air if a hot place is very cold. if hell is frozen: self.sprout_wings() self.altitude += 10 self.velocity += 25 else: self.splat() ;) The Python 'is' operator does not do what you think it does. If it did, 'hell is frozen' would mean that one could say 'war is frozen', which makes no sense. No, I think this calls for a LISP-style predicate: if frozenp(hell): ChrisA -- https://mail.python.org/mailman/listinfo/python-list
Re: imperative mood in docstrings
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
