[Python-Dev] question about docstring formatting (original) (raw)

Ben Finney ben+python at benfinney.id.au
Fri May 29 04:41:04 CEST 2009

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

More information about the Python-Dev mailing list