[Python-ideas] Multi-line comment blocks. (original) (raw)

Devin Jeanpierre jeanpierreda at gmail.com
Sat Jun 16 04:27:17 CEST 2012

On Fri, Jun 15, 2012 at 6:51 PM, Guido van Rossum <guido at python.org> wrote:

On Fri, Jun 15, 2012 at 3:47 PM, David Gates <gatesda at gmail.com> wrote:

My proposal wasn't for people who hand-code the single-line comment syntax but for those that use multi-line string comments.  Since the multi-line string hack's BDFL-approved, people will use it and other people will have to deal with it. What's wrong with it?

It behaves "badly" in a lot of circumstances. If you put it in an expression, it's treated as a string (not as an invisible thing) (IMHO this is its worst failing, the rest is just fluff). And to add on some more reasons, if you put it at the top of a file, class statement, or def statement, it's treated as a docstring, which may accidentally be included in autogenerated docs. In fact, for some common tools (epydoc), even if you put it in some other places it may be grabbed as a docstring (e.g. if you put it after a variable definition inside a class statement), and be included in the documentation. Basically the Python tool world seems to think that strings that aren't inside an expression are "docstrings", not comments, and you have to be careful to avoid being misinterpreted by your tools, which is unfortunate.

In contrast, the reason that multiline comments are so great is that they can go virtually anywhere without too much concern. For example:

def foo(a, b(*=None*)):
    ...

In this hypothetical code, I commented out the =None in order to run the test suite and see if any of my code omitted that argument, maybe to judge how reasonable it is to remove the default. Here, neither "#" comments nor docstrings really make this easy. The closest equivalent is:

def foo(a, b): #=None):
    ...

And that has to be done entirely by hand, and might be especially painful (involving copy-paste) if it isn't the last argument that's being changed.

I have done this sort of thing (commenting out stuff inside def statements) many times, I don't even remember why. It crops up.

Of course, multiline comments go anywhere, not just in def statements. And they span multiple lines! In practice, most of the time that's just as easy with the editor key that inserts "#", I just wanted to point out a case where no existing solution makes it so easy.

-- Devin

More information about the Python-ideas mailing list