Doc strings for a standalone app??

[Calvin Spealman]

Does it make sense to use doc strings rather than #-comments for a
standalone Python app? If the classes aren't going to be re-used or
imported, do they need them?

Sure. They are more clear as to the assignment of the comment to a
particular class or function or method, for one thing. It can help when
debugging and/or testing your modules, for another thing. And, you never
know that you'll always release as a standalone, as you might change your
mind or release some of your modules for third-party usage, for a third
thing.
--

 

[j_mckitrick]

Does it make sense to use doc strings rather than #-comments for a
standalone Python app? If the classes aren't going to be re-used or
imported, do they need them?

 

[Peter Hansen]

Does it make sense to use doc strings rather than #-comments for a
standalone Python app? If the classes aren't going to be re-used or
imported, do they need them?

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?

-Peter

 

[j_mckitrick]

Sure. They are more clear as to the assignment of the comment to a
particular class or function or method, for one thing. It can help when
debugging and/or testing your modules, for another thing. And, you never
know that you'll always release as a standalone, as you might change your
mind or release some of your modules for third-party usage, for a third
thing.
--

How do they help during debugging/testing?

 

[Rick L. Ratzel]

The only perceived disadvantages that I'm aware of occur when you don't
use the -OO flag. Docstrings end up in frozen executables and .pyc
files, visible through the use of the "strings" command (which is a
problem for people who think the information is hidden from the binary
file like a comment). The binary files are also ever so slightly larger
when docstrings are used instead of comments. However, using -OO
removes docstrings in addition to applying optimizations...the frozen
executable or resulting .pyo files have no docstrings and are a bit smaller.

-Rick Ratzel

 

[Peter Hansen]

The only perceived disadvantages that I'm aware of occur when you don't
use the -OO flag. Docstrings end up in frozen executables and .pyc
files, visible through the use of the "strings" command (which is a
problem for people who think the information is hidden from the binary
file like a comment). The binary files are also ever so slightly larger
when docstrings are used instead of comments. However, using -OO
removes docstrings in addition to applying optimizations...the frozen
executable or resulting .pyo files have no docstrings and are a bit
smaller.

Good point, but this is hardly a disadvantage of docstrings *relative
to regular comments*, which aren't even included in the .pyc files
under any conditions, -OO or not...

-Peter

 

[Rick L. Ratzel]

I think docstrings have a legitimate disadvantage in certain
situations. If you use a hash-sign comment, you're guaranteed that it
won't be in the binaries, which is a big advantage to some if that
comment contains highly sensitive documentation.

-Rick

 

[Roger Binns]

Does it make sense to use doc strings rather than #-comments for a
standalone Python app? If the classes aren't going to be re-used or
imported, do they need them?

Doc strings are useful for documenting your app

For example if you run epydoc on the code you will get a very good
overview of what is going on. That is then very useful to other
programmers, or yourself several months later. And if you ever
sell the code, you'll get a lot more for it

Roger

 

[Peter Hansen]

I think docstrings have a legitimate disadvantage in certain
situations. If you use a hash-sign comment, you're guaranteed that it
won't be in the binaries, which is a big advantage to some if that
comment contains highly sensitive documentation.

I suppose that's true. I thought the type of documentation
we were talking about was just API-related stuff, but I suppose
in some places of employment even that might need filtering:

function name: launchApp
inputs: string containing path to application
outputs: boolean, indicating success if true
description: This function launches the specified application if
it can be found. Note: special hacks in place to slow launching
of non-Microsoft applications! This function should be the one
we publicize to our third-party developers. Suckers.... -BG

 

[Timo Virkkala]

function name: launchApp
inputs: string containing path to application
outputs: boolean, indicating success if true
description: This function launches the specified application if
it can be found. Note: special hacks in place to slow launching
of non-Microsoft applications! This function should be the one
we publicize to our third-party developers. Suckers.... -BG

Now that would explain _quite_ a few things...

But seriously, I think that deciding on whether to use docstrings or normal
comments should be regarding to whether they do any harm, not whether they
do any good.

 

[David Fraser]

Doc strings are useful for documenting your app

For example if you run epydoc on the code you will get a very good
overview of what is going on. That is then very useful to other
programmers, or yourself several months later. And if you ever
sell the code, you'll get a lot more for it

Roger

I use the doc string as the description to give to optparse, so that it
appears in the command line help...

 

[j_mckitrick]

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?

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?

jonathon

 

[Peter Otten]

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

 

[Peter Hansen]

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?

That makes total sense. I never even considered using doc-strings
for anything but API type information. I'm not sure why... perhaps
because that's how they are used in all the standard library code,
or perhaps just because it doesn't seem to make any sense having
maintenance-related information available in the module at runtime.

I suppose if they had been intended for maintenance info, they
would have been called "comment strings", and not "doc strings"...

-Peter