On Feb 17, 2011, at 6:47 AM, Werner F. Bruhin wrote:
> Sphinx/docutils is expanding tabs to 8 spaces which looks odd/ugly, to
> work around this I convert tabs to 4 spaces when pulling doc strings but
> it does make things easier if the following could be changed on
> http://wiki.dabodev.com/CodingGuidelines .
Feel free to edit the wiki - after all, that's the whole point of
having a wiki! :)
> or even nicer (in the final doc):
>
> def someComplexMethod(self,val, val2):
> """
> This is a very complex method. In order for you to understand
> what it's doing, I need to explain a lot of the steps involved, so
> that's why this docstring is so long.
>
> :param val: an explanation for val
> :param val2: what is val2
> :rtype: a list of strings or whatever
>
> If one includes some code, prefix it with two columns and a blank line
> and indent it::
>
> x = someComplexMethod(x1, x2)
>
> Followed by a blank line and optionally some more stuff.
> """
As long as this is used sparingly, it's fine. In the case of 'complex'
methods, it can be useful, but I detest documentation that exhaustively
documents every parameter as if it were Java. The parameter names should be as
self-documenting as possible, and the types should be either obvious or not
important.
As a corollary, if the method is so complex that it needs a book to
explain it, that's more of a flag for refactoring than a call for a better
docstring. I am particularly guilty of this, as I tend to write code that
reflects my understanding of the process, rather than in a way that I can best
explain to others. Look at ClassDesigner.py to see what I mean. ;-)
-- Ed Leafe
_______________________________________________
Post Messages to: [email protected]
Subscription Maintenance: http://leafe.com/mailman/listinfo/dabo-users
Searchable Archives: http://leafe.com/archives/search/dabo-users
This message:
http://leafe.com/archives/byMID/[email protected]
