[Python-Dev] Best practice for documentation for std lib

[Steven D'Aprano]

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
> subject. 

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 
subject nouns.

"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 
docstrings :-)


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


-- 
Steven