On 6/26/2013 9:56 PM, Guido van Rossum wrote:
PEP 257 says this on the formatting of multi-line docstrings:
"""
Multi-line docstrings consist of a summary line just like a one-line
docstring, followed by a blank line, followed by a more elaborate
description.
fileinput has docstrings like
Terry Reedy writes:
> Ok, I won't add them when a function's name actually makes what it does
> obvious. But when I have to spend at least a few minutes reading the
> body to make sense of it, I will try to add the summary line that I wish
> had been there already.
+1 That's a *great* rul
Antoine Pitrou writes:
> I don't always find it easy to summarize a function in one line.
Difficulty in coming up with an accurate one-line summary of the intent
of a function is a code smell: the function probably needs to be
simplified so it is easier to describe accurately.
This is, IMO, one
On Thu, Jun 27, 2013 at 10:20 AM, Guido van Rossum wrote:
> On Thu, Jun 27, 2013 at 1:21 AM, Antoine Pitrou
> wrote:
> > I don't always find it easy to summarize a function in one line.
>
> Neither do I. But I always manage to do it anyway.
+1
If you cannot summarize what your function does i
On 6/27/2013 12:57 PM, Guido van Rossum wrote:
It was never my intention to enforce that everything has a docstring.
Just that if it does, it looks good.
Ok, I won't add them when a function's name actually makes what it does
obvious. But when I have to spend at least a few minutes reading the
It was never my intention to enforce that everything has a docstring.
Just that if it does, it looks good.
On Thu, Jun 27, 2013 at 9:40 AM, Terry Reedy wrote:
> On 6/27/2013 11:57 AM, Guido van Rossum wrote:
>>
>> Yes on one line, capitalized, period. No on single sentence.
>
>
> Complete and cor
On 6/27/2013 11:57 AM, Guido van Rossum wrote:
Yes on one line, capitalized, period. No on single sentence.
Complete and correct docstrings are somewhat rare in idlelib.
About half are missing.
Single lines typically omit the period.
Multiple lines often omit the blank line after the first.
I
Yes on one line, capitalized, period. No on single sentence.
--Guido van Rossum (sent from Android phone)
On Jun 27, 2013 8:17 AM, "Larry Hastings" wrote:
> On 06/26/2013 08:56 PM, Guido van Rossum wrote:
>
> PEP 257 says this on the formatting of multi-line docstrings:
>
> """
> Multi-line doc
On 06/26/2013 08:56 PM, Guido van Rossum wrote:
PEP 257 says this on the formatting of multi-line docstrings:
"""
Multi-line docstrings consist of a summary line just like a one-line
docstring, followed by a blank line, followed by a more elaborate
description. The summary line may be used by au
On Thu, Jun 27, 2013 at 1:21 AM, Antoine Pitrou wrote:
> I don't always find it easy to summarize a function in one line.
Neither do I. But I always manage to do it anyway. My reasoning is,
you can always leave out more detail and add it to the subsequent
paragraph.
--
--Guido van Rossum (pytho
Le Wed, 26 Jun 2013 18:56:10 -0700,
Guido van Rossum a écrit :
> PEP 257 says this on the formatting of multi-line docstrings:
>
> """
> Multi-line docstrings consist of a summary line just like a one-line
> docstring, followed by a blank line, followed by a more elaborate
> description. The summ
Skip Montanaro writes:
> Where I can [conform to PEP 257], I do, however I often find it
> difficult to come up with a one-liner, especially one that mentions
> the parameters to functions.
I think it's far better to make the synopsis a summary of the purpose of
the function; no need to force th
On 06/26/2013 07:08 PM, Skip Montanaro wrote:
I'd like to urge stdlib contributors and core devs to
heed it -- or explain why you can't.
Where I can, I do, however I often find it difficult to come up with a
one-liner, especially one that mentions the parameters to functions.
If the one-line ru
> I'd like to urge stdlib contributors and core devs to
> heed it -- or explain why you can't.
Where I can, I do, however I often find it difficult to come up with a
one-liner, especially one that mentions the parameters to functions.
If the one-line rule is going to be violated, I go whole hog an
PEP 257 says this on the formatting of multi-line docstrings:
"""
Multi-line docstrings consist of a summary line just like a one-line
docstring, followed by a blank line, followed by a more elaborate
description. The summary line may be used by automatic indexing tools;
it is important that it fi
15 matches
Mail list logo
