A case for "real" multiline comments

Chris Angelico rosuav at gmail.com
Thu Apr 19 02:56:05 EDT 2012


On Thu, Apr 19, 2012 at 4:04 PM, Cameron Simpson <cs at zip.com.au> wrote:
> Bah! To get into a function's docstring they need to be parsed by the
> Python compiler. Ergo, not comments.
>
> Calling them comments in disguise is a bit of a stretch.

They're fundamentally the same thing as Doxygen/Javadoc/etc comments.
The interpreter could easily have been written to take the contents of
a comment immediately preceding a function definition and store it as
an attribute. It's not fundamentally a literal string, because there's
nowhere for it to "go". It's a special feature of the parser that
takes a pile of text and stores it somewhere for self-documentation
purposes.

> Sorry, he's made a misparsed program (not parsed as he intended) by
> using a string where he should have used a comment? And because of this
> he says we need (or should want) multiline comments?

Since Python doesn't have multiline comments, triple-quoted strings
are sometimes pressed into service. In this particular instance, a
triple-quoted string *cannot* be used. Ergo, he is making the case
that Python needs multiline comments. It makes perfectly good sense.
You can disagree with it, but you can't scoff at his logic.

> A multiline comment can just as easily be misused to similar effect:
>
>  list = [
>  Object1(arg) /* bored now
>  Object2(arg),
>  Object3(arg),
>  */
>  Object4(arg)
>  ]

Heh, you can do far worse with slash-star comments.

list = [
   Object1(arg),
   Object2(arg), /*
   Object3(arg),  * Important comment
   Object4(arg),  */
   Object5(arg),
]

Oops, just how many objects are in that list?

> I'd be more included to call implicit string concatenation a syntax
> flaw, for all that it makes breaking strings us pretty nice.
>
> | You just happen to disagree, and you prefer single line comments. :)
>
> With cited reasons.

Yes, so let's have a sane discussion :) I do see your reasons, and
there's no perfect solution.

> A multiline comment can have its top or bottom off the screen, so the
> reader need not know they're looking at commented out code. And the
> number of parse errors I've seen where the offending comment opener was
> WAY WAY back in the code because someone forgot or removed a closing
> comment marker is huge.

Yep. That's a pretty tricky one to find, if your editor doesn't
color-code comments. It's also tricky to handle when your editor is
buggy. As mentioned, I use SciTE; a while back, there was an odd
little bug in it with regard to a combination of #if and /* and #endif
and */ in some order, and the parser did get confused. (The author is
pretty good at dealing with reported bugs, though. It didn't take long
from report to patch.) But in the normal case, where you're using a
decent editor that knows what's commented and what's not? It's pretty
easy to figure out what's going on. And if someone mucked up comment
markers in an edit, source control should help you pin the error down.

> | ... preprocessor #if 0 #endif pair.
>
> Which are also something of a pain to match up, leading to (hopefully
> correctly labelled) #endifs thus:
>
>  #endif /* !FEATUREMACRO */

Well, I was thinking of having *only* the #if 0 construct, nothing
else, so there's no need to worry about matching them up.

> I realise I could paint myself into opposing all multiline constructs,
> especially loops and ifs, but I am generally quite happy with single
> line comments. For one thing, they pretty much force you to mark all the
> lines with leading comment syntax; you can't ever be misled.

Yes, that is true. It's tedious, though, when you want to quickly
remove a dozen lines of code; most editors that allow you to
block-comment code have only one way of doing it, and if that way
doesn't suit your personal style, it grates. I'd still rather have a
proper multiline comment.

So, here's a proposal. (Maybe I should take this part to another list
or the Python issue tracker.) Introduce a new keyword or reuse
existing keywords to form a marker that unambiguously says "Ignore
these lines" and then subsequently "Stop ignoring lines". These
markers must go on their own lines, optionally with whitespace and/or
a one-line comment, but nothing else. This could accidentally
terminate or nest if a triple-quoted string contains Python code, but
that would always be an issue.

Option 1: New keyword.

comment def
... parser completely ignores these lines ...
comment break

Option 2: Reuse keywords.

from None import
... ignore these lines ...
from True import

The exact choice of keywords is open to discussion, I just looked at
keyword.kwlist on my Python 3.2 and tried to come up with something.
This syntax looks like it wouldn't nest, so it's unideal for the
proposal.

Does Python need multi-line code removal? And if so, will something
like this work?

Chris Angelico



More information about the Python-list mailing list