[Python-Dev] question about docstring formatting

[Ben Finney]

David Goodger <goodger at python.org> writes:

> Even if there were no supporting tools, I think it is useful to
> express the intent of a class/method/function in a single line. The
> process of distilling the description down can, in itself, be
> illuminating. To imitate the Zen: if the code can't be described in a
> short sentence, it may be too complicated.

Absolutely. If you can't describe what the (function, class, module)
does succinctly in a single line, how on earth are you going to choose
an appropriate short-but-descriptive name for it?

This constraint is well worth keeping, for exactly the reasons David
says above.

> I'm not saying that this should be enforced in any way. It's just a
> guideline. If a tool needs a short summary and the docstring doens't
> have a one-liner, I'd expect the tool just to take the first line and
> add ellipsis ("...").

Which in itself would be annoying enough to apply social pressure from
others to get the synopsis into a single line — so again, I approve :-)

-- 
 \     “Men never do evil so completely and cheerfully as when they do |
  `\        it from religious conviction.” —Blaise Pascal (1623-1662), |
_o__)                                                   Pensées, #894. |
Ben Finney