Brett C. wrote:
I am going to be -42 on this one. I personally love having the
docstring below the definition line.... I can't really rationalize
> it beyond just aesthetics at the moment....
I completely agree that the current form is better. It reduces the
temptation to use boilerplate docstrings.
No comment is better than an uninformative comment. If you don't
want to spend the time to write a comment, step back and let me
read the code itself.
If the docstring is below the declaration, you needn't repeat the
declaration in the comment (and people are less tempted to do so).
Documentation and code should come from a human mind, and should
communicate to another human mind. Attempting to automate the task
of documentation creates hard-to-read code, interrupted by large
meaningless comments which, often as not, are copied from a template
and incompletely editted to be appropriate to the given function.
Sorry about the rant, but this is another of my hot buttons. The
single most disappointing thing I encountered on one project in a
large corporation was an operating system requirements document that
was being developped. The group had, at one point, a twenty-two
page document with no real content. Really, the twenty two pages
included an introduction, conclusion, table of contents, appendix,
and index. It just didn't have anything but section headings. It
was a thrilling triumph of form over function; a real Suahuab
aesthetic, to coin a term.
--Scott David Daniels
[EMAIL PROTECTED]
_______________________________________________
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
