On 2/17/11 8:46 AM, Ed Leafe wrote: > On Feb 17, 2011, at 6:47 AM, Werner F. Bruhin wrote: > >> 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. ;-) I agree. Code should always be self documenting and a long docstring like that really clutters things up... If the code and the unit tests for the code can't explain itself, refactor...
Regards, Nate _______________________________________________ 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]
