Doc strings for a standalone app??

Discussion in 'Python' started by Calvin Spealman, Jun 8, 2004.

  1. 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.
    --
     
    Calvin Spealman, Jun 8, 2004
    #1
    1. Advertising

  2. Calvin Spealman

    j_mckitrick Guest

    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?
     
    j_mckitrick, Jun 8, 2004
    #2
    1. Advertising

  3. Calvin Spealman

    Peter Hansen Guest

    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
     
    Peter Hansen, Jun 9, 2004
    #3
  4. Calvin Spealman

    j_mckitrick Guest

    Calvin Spealman <> wrote in message news:<>...
    > 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?
     
    j_mckitrick, Jun 9, 2004
    #4
  5. 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
     
    Rick L. Ratzel, Jun 9, 2004
    #5
  6. Calvin Spealman

    Peter Hansen Guest

    Rick L. Ratzel wrote:

    > 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
     
    Peter Hansen, Jun 9, 2004
    #6
  7. 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

    Peter Hansen wrote:
    > Rick L. Ratzel wrote:
    >
    >> 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, Jun 9, 2004
    #7
  8. Calvin Spealman

    Roger Binns Guest

    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?


    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
     
    Roger Binns, Jun 10, 2004
    #8
  9. Calvin Spealman

    Peter Hansen Guest

    Rick L. Ratzel wrote:

    >
    > 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
     
    Peter Hansen, Jun 10, 2004
    #9
  10. Peter Hansen wrote:
    > 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.

    --
    Timo "WT" Virkkala

    "In the battle between you and the world, bet on the world."
     
    Timo Virkkala, Jun 10, 2004
    #10
  11. Calvin Spealman

    David Fraser Guest

    Roger Binns 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?

    >
    >
    > 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...
     
    David Fraser, Jun 10, 2004
    #11
  12. Calvin Spealman

    j_mckitrick Guest

    Peter Hansen <> wrote in message news:<>...

    > 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
     
    j_mckitrick, Jun 10, 2004
    #12
  13. Calvin Spealman

    Peter Otten Guest

    j_mckitrick wrote:

    > Peter Hansen <> wrote in message
    > news:<>...
    >
    >> 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
     
    Peter Otten, Jun 10, 2004
    #13
  14. Calvin Spealman

    Peter Hansen Guest

    j_mckitrick wrote:

    > 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
     
    Peter Hansen, Jun 10, 2004
    #14
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. John Wallace
    Replies:
    0
    Views:
    496
    John Wallace
    Jul 22, 2003
  2. Matt
    Replies:
    3
    Views:
    550
    Tor Iver Wilhelmsen
    Sep 17, 2004
  3. Praveen Chhangani

    Converting a org.jdom DOC to org.w3c DOC

    Praveen Chhangani, Aug 5, 2003, in forum: XML
    Replies:
    2
    Views:
    1,020
    Johannes Koch
    Aug 7, 2003
  4. Ben

    Strings, Strings and Damned Strings

    Ben, Jun 22, 2006, in forum: C Programming
    Replies:
    14
    Views:
    810
    Malcolm
    Jun 24, 2006
  5. learnerplates
    Replies:
    8
    Views:
    462
    John Bokma
    Jun 8, 2005
Loading...

Share This Page