Mailman 3 [Twisted-Python] Re: [Twisted-commits] r17664 - This was pre-UQDS code, so in making the transition I have to add lots of docs - Twisted

newer
[Twisted-Python] What bothers ME...

[Twisted-Python] Re: [Twisted-commits] r17664 - This was pre-UQDS code, so in making the transition I have to add lots of docs

older
[Twisted-Python] twistd question

Jean-Paul Calderone

24 Jul 2006 24 Jul '06

7:29 p.m.

On Sun, 23 Jul 2006 19:11:04 -0600, Glyph Lefkowitz wrote:

...

Author: glyph Date: Sun Jul 23 19:11:03 2006 New Revision: 17664

Modified: branches/addamp-1715/twisted/protocols/amp.py Log: This was pre-UQDS code, so in making the transition I have to add lots of docs

[snip]

class Argument: + """ Base-class of all objects that take values from Amp packets and convert + them into objects for Python functions. + """

Blech. Does this style of docstring formatting make anyone else barf? I notice that jml pointed out on the review of #1940 that the coding standard nominally requires this. Two points: * I think the coding standard is unclear in what it is trying to communicate. It gives an example of a docstring with no leading newline and from this one might infer that all docstrings should omit leading newlines, when really it is suggesting that simple, single-line lead-ins to docstrings belong on the same line as the opening triple quotes. * I don't think what the coding standard says is actually relevant anymore. This was a display hack to appease a very old version of epydoc. pydoctor and even the current version of epydoc don't care about this whitespace. I think the style prevalent throughout the unit tests is ideal: """ Blah. """ This is the easiest to read. It is unfortunate the emacs has such a hard time with this construct, but I think it is what we should adopt anyway. Jean-Paul

Show replies by date

James Y Knight

24 Jul 24 Jul

9:42 p.m.

New subject: [Twisted-Python] Re: [Twisted-commits] r17664 - This was pre-UQDS code, so in making the transition I have to add lots of docs

On Jul 24, 2006, at 9:59 AM, Jean-Paul Calderone wrote:

...

...
class Argument: + """ Base-class of all objects that take values from Amp packets and convert + them into objects for Python functions. + """

Blech. Does this style of docstring formatting make anyone else barf?

No, I can't say it does. However, it does make me usually miss the first line the first time through and then have to back up and read it again. So in that respect, it's non-optimal. James

glyph＠divmod.com

10:42 p.m.

New subject: [Twisted-Python] Re: [Twisted-commits] r17664 - This was pre-UQDS code, so in making the transition I have to add lots of docs

On Mon, 24 Jul 2006 09:59:52 -0400, Jean-Paul Calderone wrote:

...

This is the easiest to read.

I agree, and I'll gladly change that branch, but I didn't think it made sense to change the coding standard for the previous one. Do you want to update the coding standard to be a bit less vague in this area?

...

It is unfortunate the emacs has such a hard time with this construct, but I think it is what we should adopt anyway.

Emacs actually does a better job with the additional newline, because if you ask it to *without* the additional newline, it wraps the first line of the _docstring_ to 80 chars, it ignores indentation. I've been ignoring that for the moment because it is seldom actually an issue, but it still bothers me.

Pavel Pergamenshchik

25 Jul 25 Jul

1:15 a.m.

New subject: [Twisted-Python] Re: [Twisted-commits] r17664 - This was pre-UQDS code, so in making the transition I have to add lots of docs

On 7/24/06, Jean-Paul Calderone wrote:

...

I think the style prevalent throughout the unit tests is ideal:

""" Blah. """

This is the easiest to read. It is unfortunate the emacs has such a hard time with this construct, but I think it is what we should adopt anyway.

I disagree. I don't think this style is a lot more readable, and it adds to the line count. Extra lines make things not fit into a pageful, and it shows -- our unit tests are a pain to scroll through.

Duncan McGreggor

1:33 a.m.

New subject: [Twisted-Python] Re: [Twisted-commits] r17664 - This was pre-UQDS code, so in making the transition I have to add lots of docs

Jean-Paul Calderone wrote:

...

On Sun, 23 Jul 2006 19:11:04 -0600, Glyph Lefkowitz

...
class Argument: + """ Base-class of all objects that take values from Amp packets and convert + them into objects for Python functions. + """

Blech. Does this style of docstring formatting make anyone else barf?

I'll cast my vote: Yes, it does induce nausea. I actually can't stand it and much prefer your proposed syntax. In fact, my behavior verges on obsessive, including the need to change it in code I am contributing when I see it otherwise. d

Stephen Waterbury

5:25 a.m.

New subject: [Twisted-Python] Re: [Twisted-commits] r17664 - This was pre-UQDS code, so in making the transition I have to add lots of docs

Duncan McGreggor wrote:

...

Jean-Paul Calderone wrote:

...
On Sun, 23 Jul 2006 19:11:04 -0600, Glyph Lefkowitz

...
class Argument: + """ Base-class of all objects that take values from Amp packets and convert + them into objects for Python functions. + """ Blech. Does this style of docstring formatting make anyone else barf?

I'll cast my vote:

Yes, it does induce nausea. I actually can't stand it and much prefer your proposed syntax. In fact, my behavior verges on obsessive,

OK, it appears that the voting has begun in earnest ... I actually thought everyone would agree with Jp, but since they don't (shocking!) ... I also vote for the """ Blah ... """ format (which I have always used). Steve

Jonathan Lange

5:37 a.m.

New subject: [Twisted-Python] Re: [Twisted-commits] r17664 - This was pre-UQDS code, so in making the transition I have to add lots of docs

On 7/24/06, Jean-Paul Calderone wrote:

...

On Sun, 23 Jul 2006 19:11:04 -0600, Glyph Lefkowitz wrote:

...
Author: glyph Date: Sun Jul 23 19:11:03 2006 New Revision: 17664

Modified: branches/addamp-1715/twisted/protocols/amp.py Log: This was pre-UQDS code, so in making the transition I have to add lots of docs

[snip]

class Argument: + """ Base-class of all objects that take values from Amp packets and convert + them into objects for Python functions. + """

Blech. Does this style of docstring formatting make anyone else barf? I notice that jml pointed out on the review of #1940 that the coding standard nominally requires this.

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. Also, I strongly object to using """ Blah. """ for one line docstrings. -0 on changing docstring format +1 on updating coding standard to be clearer jml

Andrew Bennetts

6:49 a.m.

New subject: [Twisted-Python] Re: [Twisted-commits] r17664 - This was pre-UQDS code, so in making the transition I have to add lots of docs

On Tue, Jul 25, 2006 at 10:07:44AM +1000, Jonathan Lange wrote: [...]

...

Also, I strongly object to using """ Blah. """ for one line docstrings.

I agree with this sentiment. For multi-line docstrings, I don't care. Both formats are equally readable to me.

...

+1 on updating coding standard to be clearer

More clarity is more good! -Andrew.

Stephen Waterbury

7:33 a.m.

New subject: [Twisted-Python] Re: [Twisted-commits] r17664 - This was pre-UQDS code, so in making the transition I have to add lots of docs

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.

Jean-Paul Calderone

8:10 a.m.

New subject: [Twisted-Python] Re: [Twisted-commits] r17664 - This was pre-UQDS code, so in making the transition I have to add lots of docs

On Mon, 24 Jul 2006 22:03:12 -0400, Stephen Waterbury 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

Jonathan Lange

8:13 a.m.

New subject: [Twisted-Python] Re: [Twisted-commits] r17664 - This was pre-UQDS code, so in making the transition I have to add lots of docs

On 7/25/06, Jean-Paul Calderone wrote:

...

This bothers me a lot, though:

""" Blah. """

Me too.

glyph＠divmod.com

8:46 p.m.

New subject: [Twisted-Python] Re: [Twisted-commits] r17664 - This was pre-UQDS code, so in making the transition I have to add lots of docs

On Tue, 25 Jul 2006 10:07:44 +1000, Jonathan Lange wrote:

...

I don't have strong feelings about how docstrings should be formatted. However I would prefer it if we used PEP 257 formatting.

I just read PEP 257. What features in particular are you referring to? Most of it seems to be about encoding redundant information. By section: "What is a Docstring?" - I think we all know - "Use triple quotes", sure. "One Line Docstrings" Hopefully we should have only a few of these, it seems odd to dedicate so much verbiage to them. "Multi-Line Docstrings" - One-line summary: not always possible. Following another aspect of our coding standard, a "line", in a method-level docstring, is at most 72 characters, you've burned a minimum of 8 in indentation, and that's often not enough space to summarize. One sentence summary? Sure. - Blank line before and after class docstrings? I don't see this followed anywhere. Especially not *before* docstrings: the convention is: class X: """ ... pretty much everywhere. I don't see any reason to change it. - "docstring of a script..." not applicable because of t.p.u.O - "list the classes..." not applicable because of pydoctor - "docstring for a function..." ... yes, it should describe arguments, side effects, return values; what else would it do? - "docstring for a class..." not applicable again because of pydoctor; this information is redundant - "if a class subclasses another class..." not applicable again because of pydoctor's inheritance listing - "DO NOT use the Emacs convention..." uh yeah, also don't spell all your method names wrong or use synonyms for them "handling docstring indentation" - this whole section is about docstring processing tools, which, unless I manage to convince mwh to embed pydoctor in lore for some reason, Twisted is not :).

Michael Hudson

8:59 p.m.

glyph@divmod.com writes:

...

- One-line summary: not always possible. Following another aspect of our coding standard, a "line", in a method-level docstring, is at most 72 characters, you've burned a minimum of 8 in indentation, and that's often not enough space to summarize. One sentence summary? Sure.

As we've just discussed on #twisted, these one line summaries are currently used by pydoctor -- it uses the first non-blank line of the docstring(in terms of "lines in the source file") in the "summary table" at the top of each page. The long term solution is probably to fix pydoctor to have some cleverer way of finding this summary, while still not ending up with vast reams of text in the summary table if someone neglects to add a summary. Patches welcome :-) -- it's a job that can be very easily localized to a single function, so you don't need to try to wrap your head around any crazy code I've written... Cheers, mwh -- python py.py ~/Source/python/dist/src/Lib/test/pystone.py Pystone(1.1) time for 5000 passes = 19129.1 This machine benchmarks at 0.261381 pystones/second

6483

Age (days ago)

6484

Last active (days ago)

List overview

Download

12 comments

9 participants

participants (9)

Andrew Bennetts
Duncan McGreggor
glyph＠divmod.com
James Y Knight
Jean-Paul Calderone
Jonathan Lange
Michael Hudson
Pavel Pergamenshchik
Stephen Waterbury

[Twisted-Python] Re: [Twisted-commits] r17664 - This was pre-UQDS code, so in making the transition I have to add lots of docs

Jean-Paul Calderone

James Y Knight

glyph＠divmod.com

Pavel Pergamenshchik

Duncan McGreggor

Stephen Waterbury

Jonathan Lange

Andrew Bennetts

Stephen Waterbury

Jean-Paul Calderone

Jonathan Lange

glyph＠divmod.com

Michael Hudson

tags

participants (9)