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

[Guido van Rossum]

On Mon, Sep 23, 2013 at 10:52 AM, Terry Reedy <tjreedy at udel.edu> wrote:

> On 9/23/2013 10:56 AM, Guido van Rossum wrote:
>
>  I think 60 is just a guideline. In stdlib .py source code I want it not
>> to extend beyond the 79th column (see recent PEP 8 argument). For a
>>
>
> PEP 8 says "Limit all lines to a maximum of 79 characters.
>
> For flowing long blocks of text with fewer structural restrictions
> (docstrings or comments), the line length should be limited to 72
> characters."
>
> I do not understand 72 instead of 79, but to me, that means 72 chars
> total, including indents, triple quote and period, which means the cursor
> not past 73. If that is not what you mean, please clarify.


This is partly based on Emacs defaults (when I hit ESC-q, it reflows a
paragraph using the 72 char limit), partly on old punched card conventions
(columns 73-80 were reserved for sequence numbers), partly just to limit
the line length to of *columns* of text to something a bit narrower than
the full line width (i.e. 80 chars) to improve readability.

But the PEP specifically qualifies this with "for flowing long blocks of
text" which is meant to apply only to blocks of reflowable text that don't
fit on a line.

If it fits on a line, you can go to 79.


> typical class, where the docstring is indented 4 spaces, that leaves 72
> characters for the summary line (including a final period!). For a
> method it's 68 due to the extra indent.
>

72 - 2 indents - """ - . = 60, which is a bit skimpy ;-). Why not the full
> 79 at least?
>

For the summary line, that's fine (and actually how I interpret the PEP).

-- 
--Guido van Rossum (python.org/~guido)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20130923/22e2c0be/attachment-0001.html>