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 Scott.Daniels@Acm.Org