[Twisted-Python] What bothers ME about docstrings...

Ed Suominen general at eepatents.com
Tue Jul 25 12:47:06 EDT 2006


What bothers ME most about docstrings is when they are absent!

I agree with some others in not liking when they start on the same line
as the triple quotes, but that's much further down my ample list of gripes.

By the way, David Reid did some work on docstrings for twisted.web2 and
earned the Twisted project $45 of my $2-per-docstring, $200 challenge.
(Hmmm...how did that odd number get there; did he write half a docstring
or something?) The money doesn't have to go to the Twisted project, but
that was his preference. There is another $200 available if my challenge
is met, as I understand it.

Any other takers?

Best regards, Ed

> From: Jean-Paul Calderone <exarkun at divmod.com>
> Subject: Re: [Twisted-Python] Re: [Twisted-commits] r17664 - This was
> 	pre-UQDS	code, so in making the transition I have to add lots of docs
> To: Twisted general discussion <twisted-python at twistedmatrix.com>
> Message-ID: <20060725024044.29014.857136159.divmod.quotient.52976 at ohm>
> Content-Type: text/plain; format=flowed
> 
> On Mon, 24 Jul 2006 22:03:12 -0400, Stephen Waterbury <golux at comcast.net> wrote:
>> Jonathan Lange wrote:
>>> The standard is definitely unclear.
>>>
>>> I don't have strong feelings about how docstrings should be formatted.
>>> However I would prefer it if we used PEP 257 formatting.
>> Just for the record, the multi-line docstring format
>>
>> """
>> Blah blah blah blah blah
>> blah.
>> """
>>
>> is consistent with PEP 257's recommendations.
>>> Also, I strongly object to using
>>> """
>>> Blah.
>>> """
>>> for one line docstrings.
>> It doesn't bother me, but
>>
>> """Blah."""
>>
>> doesn't either, for one-liners.
>>
> 
> This one doesn't really bother me either, although I very slightly prefer
> the long form.
> 
> This bothers me a lot, though:
> 
> """ Blah. """
> 
> Jean-Paul





More information about the Twisted-Python mailing list