[Doc-SIG] Re: PEP 257: Docstring Conventions

[Sam Penrose]

Sorry for the delay in getting back to you; I was on vacation.

My mistake on the purpose of 257.

What is readable depends in on context. I think Guido's
Style Guide is basically great but too specific in some ways and not
specific enough in others to use as a spec. The Guide mashes together
commentary which, when made a spec, is appropriate for differing
contexts:

1) The minimum necessary for cross-platform and cross-editor
development.

2) Additional layers and conventions important for those contributing
to Python release code so that they can work together.

3) What Guido thinks looks good; the "for symetry" comment I singled
is one example; "The closing quotes are on the same line as the opening
quotes. This looks better for one-liners" is another. While I happen to
agree with this and follow it, I don't think it belongs in a
specification (as opposed to a Style Guide). I am a little uncomfortable
with your comment that "the DPS will know about some of the
conventions, so following them will get you the best results." "Getting
the best results" has the sound of "a little bit pregnant" to me, as do
some of your other phrases. What is style and what is spec?

4) To be crystal clear: I would like to see a clear line between which
standards can be violated at the cost of dirty looks and which will
cause DSP code to fail, and I'd like to see some of the current PEP
contents explicitly moved to the first category.

this-opinion-is-worth-what-you-paid-for-it-ly,
S

On Thu, 14 Jun 2001, you wrote:
> on 2001-06-13 4:45 PM, Sam Penrose (sam@ddmweb.com) wrote:
> >>>> This is a PEP-ification of part of Guido van Rossum's Python Style
> > Guide ... <<<
> > 
> > parts of the Style Guide weather the conversion to a specification
> > better than others. For example...
> [omitted]
> > .... seems a bit visually oriented for the purpose of making
> > docstrings machine-parseable.
> 
> Making docstrings machine-parsable is not the point of PEP 257, nor of the
> Style Guide from which it sprang. The point is to standardize the high-level
> structure of docstrings: what should they contain, and how to say it
> (without touching on any markup syntax within docstrings). Docstring spacing
> is one of the conventions that make Python code readable, IMHO. The
> Docstring Processing System is made up of layers of specs. PEP 257 is the
> highest-level, semantic part.
> 
> The PEP contains conventions, not laws or syntax. If you violate the
> conventions, the worst you'll get is some dirty looks. But the DPS will know
> about some of the conventions, so following them will get you the best
> results.
> 
> BTW, what's wrong with that specific convention?
> 
> -- 
> David Goodger    dgoodger@bigfoot.com    Open-source projects:
>  - Python Docstring Processing System: http://docstring.sf.net
>  - reStructuredText: http://structuredtext.sf.net
>  - The Go Tools Project: http://gotools.sf.net