On 17/02/2011 14:46, Ed Leafe wrote: > 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! :) > Changing CodingGuidelines just like this - I heard of people being killed for less;-) >> 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. Agree, but as soon as they need explanation then I think the table format is preferred instead of having to need to read a whole paragraph.
Will have a go and redo this on the wiki in the next few days. Werner _______________________________________________ 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]
