David Goodger <good...@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
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
