Doc strings for a standalone app??
__peter__ at web.de
Thu Jun 10 13:23:10 CEST 2004
> Peter Hansen <peter at engcorp.com> wrote in message
> news:<TJKdnU62dcH5bVvdRVn-gQ at powergate.ca>...
>> The only thing I can think of to ask about that is "Why
>> would you *not* want to use doc strings?". There is
>> no significant overhead associated with them, so you
>> don't really lose. They have potential advantages, given
>> that the docs are available at runtime, more clearly
>> identifiable as documentation, etc, whereas the other
>> form of comments have no advantages for this kind of
>> thing. So why not use them?
> Well, I can see that doc strings can be useful at the beginning of
> each module/class/method/function. But since comments can be spread
> throughout the code, explaining logic as needed, aren't they more
> useful to someone who needs to maintain, rather than just use, your
I just came across an example where too many comments *obscured* the logic
of a script. If you fear that your program cannot be understood without
comments, try to express your intentions more clearly _in_ _code_ and
reduce the number of # comments to the absolute minimum.
> It SEEMS to me that doc strings are for those who will USE your code,
> and comments for those who will MAINTAIN it. Does that make any
The doc strings are/should be useful for both users and maintainers. In
addition, maintainers can take advantage of a testsuite, either unit tests
or - doc strings again - doctest. Comments are crutches.
More information about the Python-list