470,810 Members | 888 Online
Bytes | Developer Community
New Post

Home Posts Topics Members FAQ

Post your question to a community of 470,810 developers. It's quick & easy.

Doc strings for a standalone app??

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?
Jul 18 '05 #1
4 1593
j_mckitrick wrote:
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.
--

Jul 18 '05 #2
j_mckitrick wrote:
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
Jul 18 '05 #3
Calvin Spealman <ca****@ironfroggy.com> wrote in message news:<ma*************************************@pyth on.org>...
j_mckitrick wrote:
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.
--


How do they help during debugging/testing?
Jul 18 '05 #4
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 wrote:
j_mckitrick wrote:
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

Jul 18 '05 #5

This discussion thread is closed

Replies have been disabled for this discussion.

Similar topics

reply views Thread by FilexBB | last post: by
2 posts views Thread by Lonnie, SRC employee | last post: by
9 posts views Thread by Dan Williams | last post: by
3 posts views Thread by Isaac Gouy | last post: by
7 posts views Thread by tah | last post: by
reply views Thread by mihailmihai484 | last post: by
By using this site, you agree to our Privacy Policy and Terms of Use.