[Python-Dev] Best practice for documentation for std lib
steve at pearwood.info
Tue Sep 24 03:31:56 CEST 2013
This is getting off-topic, if you're not interested in English grammar
you should stop reading.
On Mon, Sep 23, 2013 at 03:18:01PM -0400, Alexander Belopolsky wrote:
> I don't think "Returns bar." is a valid English sentence because it lacks
Subjectless sentences are unusual in English, but you do see them.
Sentences consisting of only an interjection are subjectless:
"Ouch!" "Hear hear!" "Rubbish!" "Oh dear!"
Imperative sentences often have no explicit subject:
"Close the door." "Put that light out!" "Follow me."
Conversational English (especially spoken English) often displays the
phenomenon called "Conversational Deletion", where the beginning of
sentences are eroded away, dropping (e.g.) possessives, articles, and
"Hope this helps." "See you next week." "No need to get upset!"
In the example given, "Returns bar", I would identify this as an example
of conversational deletion. The full sentence would be "This function
returns bar". Personally, I don't mind such a conversational style,
although many people consider it too informal for written English, even
> I would not mind
> def foo():
> """returns bar"""
> which I would read as "Function foo() returns bar," but in this case
> "returns" should be in lower case.
I certainly don't like that. Sentences, even eroded sentences, start
with capital letters in English. Unless you are the poet e.e. cummings,
capital letters are non-negotiable.
More information about the Python-Dev