[Python-ideas] Multi-line comment blocks.

[Devin Jeanpierre]

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