why no block comments in Python?

Discussion in 'Python' started by John Salerno, Mar 8, 2006.

  1. John Salerno

    John Salerno Guest

    I'm still tyring to figure out what "Pythonic" means, and I have a
    feeling the answer to my question may fall into that category. Are block
    comments somehow unpythonic?
     
    John Salerno, Mar 8, 2006
    #1
    1. Advertising

  2. John Salerno wrote:

    > I'm still tyring to figure out what "Pythonic" means, and I have a
    > feeling the answer to my question may fall into that category. Are block
    > comments somehow unpythonic?


    only in the sense that python don't have them.

    but they're pretty pointless, if you have a modern editor.

    (and if you don't, you can quickly comment out regions by putting them
    inside a triple-quoted string.)

    </F>
     
    Fredrik Lundh, Mar 8, 2006
    #2
    1. Advertising

  3. John Salerno

    Roy Smith Guest

    Fredrik Lundh <> wrote:
    > you can quickly comment out regions by putting them
    > inside a triple-quoted string.)


    Except that triple-quotes don't nest.

    I do agree, however, with the idea that any decent editor should be
    able to comment out a block of code faster than I can type this
    sentence.
     
    Roy Smith, Mar 8, 2006
    #3
  4. Roy Smith wrote:

    > > you can quickly comment out regions by putting them
    > > inside a triple-quoted string.)

    >
    > Except that triple-quotes don't nest.


    ''' """...except when they do""" '''

    </F>
     
    Fredrik Lundh, Mar 8, 2006
    #4
  5. John Salerno

    Warby Guest

    It's clear that if you have a modern editor, block comments are
    unnecessary because it is trivial to add a # to the start of each line
    of a block, but that doesn't really answer your question. It explains
    why you might not always need block comments but doesn't explain why
    you shouldn't use them (especially in a primitive editor).

    The danger with block comments is that there is no way to tell that the
    code you're looking at has been commented out unless you can see the
    start or end of the comment block. If you have a modern editor, it
    probably changes the color of all commented out code to eliminate
    confusion. But if you have a primitive editor it does not. Also, even
    people who use modern editors sometimes browse source code using a
    plain text viewer (less/more).

    Eliminating block comments eliminates uncertainty. :)
     
    Warby, Mar 8, 2006
    #5
  6. John Salerno

    Warby Guest

    ....and I forgot to mention that the output of grep and diff is far more
    understandable in the absence of block comments!
     
    Warby, Mar 8, 2006
    #6
  7. John Salerno

    John Salerno Guest

    Warby wrote:

    > The danger with block comments is that there is no way to tell that the
    > code you're looking at has been commented out unless you can see the
    > start or end of the comment block. If you have a modern editor, it
    > probably changes the color of all commented out code to eliminate
    > confusion. But if you have a primitive editor it does not.


    That makes sense. If you have a modern editor, you don't need blocks. If
    you don't have one, blocks don't help. :)
     
    John Salerno, Mar 8, 2006
    #7
  8. John Salerno

    Roy Smith Guest

    Warby <> wrote:
    >Eliminating block comments eliminates uncertainty. :)


    An even better way to eliminate uncertainty is to eliminate the code.
    Commenting out is fine for a quick test during development. Once the
    code is committed, the dead code should be eliminated completely.
     
    Roy Smith, Mar 8, 2006
    #8
  9. On Wednesday 08 March 2006 12:42 pm, Warby wrote:
    > The danger with block comments is that there is no way to tell that the
    > code you're looking at has been commented out unless you can see the
    > start or end of the comment block. If you have a modern editor, it
    > probably changes the color of all commented out code to eliminate
    > confusion. But if you have a primitive editor it does not. Also, even
    > people who use modern editors sometimes browse source code using a
    > plain text viewer (less/more).


    No doubt some Emacs zealot will say something snarky at this point, ;-)
    but it's also true that Vi (or gvim anyway) will occasionally get
    confused by very long block comments or triple-quoted strings,
    causing the syntax-color to get out of synch.

    I recently started running into this problem when I started using
    doctest tests. There's probably a smarter way to do this, but I
    was putting several of them in a module docstring, and it gets to
    be a 100+ lines or so of doctest plus explanations.

    I'm thinking this might be a use-case for the new support for
    doctests in a separate file. Or maybe I just need to see if I
    can move the tests into individual object docstrings.

    --
    Terry Hancock ( hancock at anansispaceworks.com )
    Anansi Spaceworks http://www.anansispaceworks.com
     
    Terry Hancock, Mar 9, 2006
    #9
  10. John Salerno

    Paddy Guest

    I have found that some editors colourize text based on parsing a
    section of text around what is visible. Long, multi-line comments or
    strings might not then get colored correctly.

    Personally, I do use block comments in other languages but maybe they
    should not exist in finished code for reasons already given by others,
    readabiity!

    Cheers, Paddy.
     
    Paddy, Mar 9, 2006
    #10
  11. John Salerno

    Benji York Guest

    Terry Hancock wrote:
    > I'm thinking this might be a use-case for the new support for
    > doctests in a separate file.


    Having doctests in their own file is (IMHO) a majorly under appreciated
    feature of doctest. The ability to do either nice user (as in
    developer) docs with known good examples or well documented
    not-meant-for-documentation unit/functional/integration tests is terrific.
    --
    Benji York
     
    Benji York, Mar 9, 2006
    #11
  12. John Salerno

    msoulier Guest

    > (and if you don't, you can quickly comment out regions by putting them
    > inside a triple-quoted string.)


    Although that will use up memory, as opposed to a comment.

    Still, it's simple enough in an editor like Vim or Emacs to highlight a
    region, and define a macro to add/remove #s. Any Python IDE should
    certainly have this capability.

    Mike
     
    msoulier, Mar 9, 2006
    #12
  13. John Salerno

    Peter Otten Guest

    msoulier wrote:

    >> (and if you don't, you can quickly comment out regions by putting them
    >> inside a triple-quoted string.)

    >
    > Although that will use up memory, as opposed to a comment.


    Doesn't seem so:

    >>> def f():

    .... "docstring"
    .... "another string"
    .... a = 42
    .... "yet another string"
    ....
    >>> f.func_code.co_consts

    ('docstring', 42, None)
    >>>


    Peter
     
    Peter Otten, Mar 9, 2006
    #13
  14. John Salerno

    Roy Smith Guest

    msoulier <> wrote:
    >> (and if you don't, you can quickly comment out regions by putting them
    >> inside a triple-quoted string.)

    >
    >Although that will use up memory, as opposed to a comment.


    I can't imagine a realistic scenario where the amount of memory wasted
    by triple-quoting out code could possibly be significant.

    I'll also repeat what I said before -- good software engineering
    practice demands that you remove dead code completely. Commenting
    something out for a quick test during development is OK, but once it
    reaches the production stage, get rid of it. It'll still live in your
    revision control system.
     
    Roy Smith, Mar 9, 2006
    #14
  15. On 9 Mar 2006 07:21:00 -0800
    "msoulier" <> wrote:
    > > (and if you don't, you can quickly comment out regions
    > > by putting them inside a triple-quoted string.)

    >
    > Although that will use up memory, as opposed to a comment.


    Not really. Unless it is the first string in the block
    (class, function, module), it won't be assigned to anything,
    and will be immediately garbage-collected.

    It may consume space in the pyc file, I'm not sure.

    Of course, I don't think anyone would advocate leaving
    such things in production code where the memory use
    would be an issue anyway. The whole point of
    block-commenting code out is to temporarily "delete" it
    without having to use your version control system to get
    it back. You only do that when you have strong feeling
    you're going to need to put it back in.

    --
    Terry Hancock ()
    Anansi Spaceworks http://www.AnansiSpaceworks.com
     
    Terry Hancock, Mar 10, 2006
    #15
  16. On Thu, 09 Mar 2006 18:02:27 -0600, Terry Hancock wrote:

    > On 9 Mar 2006 07:21:00 -0800
    > "msoulier" <> wrote:
    >> > (and if you don't, you can quickly comment out regions
    >> > by putting them inside a triple-quoted string.)

    >>
    >> Although that will use up memory, as opposed to a comment.

    >
    > Not really. Unless it is the first string in the block
    > (class, function, module), it won't be assigned to anything,
    > and will be immediately garbage-collected.
    >
    > It may consume space in the pyc file, I'm not sure.


    I don't believe this is true. Unassigned strings other than the doc string
    are not compiled into the code:

    >>> def f(x):

    .... "this is a doc string"
    .... "but this isn't"
    .... return "hello world"
    ....
    >>> dis.dis(f)

    4 0 LOAD_CONST 1 ('hello world')
    3 RETURN_VALUE
    4 LOAD_CONST 2 (None)
    7 RETURN_VALUE


    Strangely enough, this is a local optimization that appears to have been
    done only for strings:

    >>> def g():

    .... 45
    .... return 55
    ....
    >>> dis.dis(g)

    2 0 LOAD_CONST 1 (45)
    3 POP_TOP

    3 4 LOAD_CONST 2 (55)
    7 RETURN_VALUE
    8 LOAD_CONST 0 (None)
    11 RETURN_VALUE

    So you should feel free to use strings (triple-quoted or otherwise) as
    documentation in your functions.

    --
    Steven.
     
    Steven D'Aprano, Mar 10, 2006
    #16
  17. On Sat, 11 Mar 2006 10:23:56 +1100
    "Steven D'Aprano" <> wrote:

    > On Thu, 09 Mar 2006 18:02:27 -0600, Terry Hancock wrote:
    >
    > > On 9 Mar 2006 07:21:00 -0800
    > > "msoulier" <> wrote:
    > >> > (and if you don't, you can quickly comment out

    > >regions > > by putting them inside a triple-quoted
    > >string.) >
    > >> Although that will use up memory, as opposed to a

    > >comment.
    > >
    > > Not really. Unless it is the first string in the block
    > > (class, function, module), it won't be assigned to
    > > anything, and will be immediately garbage-collected.
    > >
    > > It may consume space in the pyc file, I'm not sure.

    >
    > I don't believe this is true. Unassigned strings other
    > than the doc string are not compiled into the code:


    [bytecode analysis snipped]

    Cool. I thought that was probably true, but didn't want
    to guess.

    Cheers,
    Terry


    --
    Terry Hancock ()
    Anansi Spaceworks http://www.AnansiSpaceworks.com
     
    Terry Hancock, Mar 11, 2006
    #17
  18. Warby wrote:
    > ...and I forgot to mention that the output of grep and diff is far more
    > understandable in the absence of block comments!


    Which is why people do this /anyway/. (Kind of makes block comments
    pointless, doesn't it?

    /* This is a
    * really
    * really
    * long
    * block comment */
     
    Jonathan Gardner, Mar 11, 2006
    #18
  19. John Salerno

    Roy Smith Guest

    In article <>,
    "Jonathan Gardner" <> wrote:

    > Warby wrote:
    > > ...and I forgot to mention that the output of grep and diff is far more
    > > understandable in the absence of block comments!

    >
    > Which is why people do this /anyway/. (Kind of makes block comments
    > pointless, doesn't it?
    >
    > /* This is a
    > * really
    > * really
    > * long
    > * block comment */


    Habit left over from the C days. It was the only way of making a block
    comment stand out visually. C++ has // comments, just like Python has #,
    but old habits die hard.
     
    Roy Smith, Mar 11, 2006
    #19
    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. Replies:
    0
    Views:
    1,157
  2. Mr. SweatyFinger

    why why why why why

    Mr. SweatyFinger, Nov 28, 2006, in forum: ASP .Net
    Replies:
    4
    Views:
    922
    Mark Rae
    Dec 21, 2006
  3. Mr. SweatyFinger
    Replies:
    2
    Views:
    2,077
    Smokey Grindel
    Dec 2, 2006
  4. morrell
    Replies:
    1
    Views:
    976
    roy axenov
    Oct 10, 2006
  5. Monk
    Replies:
    10
    Views:
    1,502
    Michael Wojcik
    Apr 20, 2005
Loading...

Share This Page