How to comment code?

Discussion in 'Python' started by Martin P. Hellwig, Jan 19, 2007.

  1. Hi all,

    I've been toying with python for about two years now. Not every day,
    just when I encounter something in my job (sysadmin) repetitively dull.
    The amazing thing is that like any other language (natural or not)
    learning it more gives you power to express your thoughts better and
    create something from nothing, for me this is something I can only
    compare to freedom.

    However since I'm learning more of python I've struggled with
    commenting, how should I've comment my code? I'm not talking about the
    style but more on the concept itself, things that where a couple of
    month ago a bunch of monkey poop is now as easy as reading a comic.

    I always give a brief description on what the code is supposed to do and
    I suppose that any serious coder knows way more then me about
    programming so I don't bother to comment that much since it mostly (in
    my eyes) just clutters up the code and makes it actually harder to read.

    Though this makes me uncomfortably, commenting so little, I was thinking
    that perhaps something like doctest (I'm not so much into unit testing
    or the equivalents at this moment) has the side affect to make my code
    more understandable and readable. Any practical experience you'd like to
    share with me, any other comments are welcome too of course :)

    Thanks.

    --
    mph
    Martin P. Hellwig, Jan 19, 2007
    #1
    1. Advertising

  2. Martin P. Hellwig

    James Stroud Guest

    Martin P. Hellwig wrote:
    > Hi all,
    >
    > I've been toying with python for about two years now. Not every day,
    > just when I encounter something in my job (sysadmin) repetitively dull.
    > The amazing thing is that like any other language (natural or not)
    > learning it more gives you power to express your thoughts better and
    > create something from nothing, for me this is something I can only
    > compare to freedom.
    >
    > However since I'm learning more of python I've struggled with
    > commenting, how should I've comment my code? I'm not talking about the
    > style but more on the concept itself, things that where a couple of
    > month ago a bunch of monkey poop is now as easy as reading a comic.
    >
    > I always give a brief description on what the code is supposed to do and
    > I suppose that any serious coder knows way more then me about
    > programming so I don't bother to comment that much since it mostly (in
    > my eyes) just clutters up the code and makes it actually harder to read.
    >
    > Though this makes me uncomfortably, commenting so little, I was thinking
    > that perhaps something like doctest (I'm not so much into unit testing
    > or the equivalents at this moment) has the side affect to make my code
    > more understandable and readable. Any practical experience you'd like to
    > share with me, any other comments are welcome too of course :)


    I have found it useful to familiarize myself some tool such as epydoc
    and write comments in the function doc-string. For example,

    def doit(stuff, beta, cycles):
    """
    Does nothing with I{stuff} in an infinite loop by applying a null
    operation. The I{cycles} parameter is multiplied by infinity.

    @param beta: null operator not to be applied to stuff
    @type beta: callable
    @type cycles: int
    """

    This explains paramaters, etc., for you and other users of your API and
    paves the way for automatically generated documentation. Note that it
    would be excessive to comment each and every parameter, etc. Once the
    code is working correctly, a lot of in-line comments can be removed.
    Usually, in python, correctly working code is self explanatory at the
    implementation level, especially if you attempt to code "pythonically"
    (which can roughly be defined as the best practices according to the
    python community or the community subset who post to comp.lang.python).

    If you find that your code gets very complicated and needs excessive
    commenting to understand, try to factor it into hierarchically related
    simpler functions and classes and comment each individually using
    doc-strings. In essence, think about commenting the interface rather
    than the implementation.

    Use module level doc-strings (comments) to gather usage and explanation
    notes for the most useful functions. This allows users (for example,
    you) to use your libraries without burrowing into the automatically
    generated documentation for each and every function.

    Other tools may be as useful as epydoc, but this is the general strategy
    I have converged upon.

    James
    James Stroud, Jan 19, 2007
    #2
    1. Advertising

  3. I think that doc strings are the most important way in which you should
    be commenting on your code. Once the code works, you can elimainate
    most inline comments, leaving only doc string for everything and a few
    comments on some particularly confusing parts. Other than that,
    comments usually only clutter Python code. But remember that you are
    the person who understands your code best, so don't be too fanatical
    about deleting inline comments.
    Pavel Panchekha, Jan 19, 2007
    #3
  4. Martin P. Hellwig

    gonzlobo Guest

    If it's hard to write, it should be hard to read! :)

    On 1/19/07, Martin P. Hellwig <> wrote:
    > Hi all,


    (snip)
    > However since I'm learning more of python I've struggled with
    > commenting, how should I've comment my code

    (snip)
    gonzlobo, Jan 19, 2007
    #4
    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. Analog_Guy
    Replies:
    6
    Views:
    551
    Andy Peters
    Jun 1, 2005
  2. John Smith

    how to comment-out aspx code

    John Smith, Oct 4, 2004, in forum: ASP .Net
    Replies:
    2
    Views:
    15,407
    John Smith
    Oct 6, 2004
  3. =?Utf-8?B?bmV0Y29tbWFuZGVy?=

    Generating XML comment documents from ASP.NET C# code-behind

    =?Utf-8?B?bmV0Y29tbWFuZGVy?=, Jan 25, 2006, in forum: ASP .Net
    Replies:
    1
    Views:
    774
    Rick Strahl [MVP]
    Jan 25, 2006
  4. Alec S.
    Replies:
    10
    Views:
    10,120
    Alec S.
    Apr 16, 2005
  5. sci
    Replies:
    1
    Views:
    351
    Kevin Goodsell
    Apr 13, 2004
Loading...

Share This Page