On 17/02/2011 11:08 a.m., Nate Lowrie wrote:
> 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...
And that is why Python's help documentation does not automatically
include docstrings directly from the code, but keeps docstrings and
documentation as separate things.
If you are reading code you get to see the method and get some idea of
what every parameter is supposed to do, and if you are intending to
modify the code you'll certainly get to look at the unit tests and any
other info first. OTOH if you are *using* (as opposed to modifying) the
framework you only want to interact with the help documents, as the
final aim is not to understand how the framework works but only to
understand how to *use* the framework. That is why docstrings and help
documentation are not the same.
We have three possible (as far as I see it) paths here :
- help will come from docstrings
- docstrings will be written thinking in framework developers
- docstrings will be written thinking in framework users
- help will come from help documentation which is written for
framework users and not necessarily the same as the docstrings.
_______________________________________________
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]
