Doc strings for a standalone app??

[Peter Otten]

j_mckitrick wrote:

> 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
> code?

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
> sense?

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.

Peter