A case for "real" multiline comments

[Alek Storm]

I think docstrings should look like strings, because they're essentially
data: they end up as the __doc__ attribute of whatever class or function
they're documenting. Conversely, they shouldn't be used as multi-line
comments that aren't data (in the middle of functions) - the parser should
disallow strings as stand-alone expressions after the initial docstring.
This wouldn't solve Jordan's problem outright, since his string was inside
a list, but it may prevent people from making that mistake in the future,
since docstrings would have a purpose more specialized than "multi-line
comment".

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

I believe the more Pythonic syntax would be:

comment:
    ...some
    ...indented
    ...lines

God help us if that ever happens.

Alek

On Thu, Apr 19, 2012 at 1:56 AM, Chris Angelico <rosuav at gmail.com> wrote:

> 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.
>
> 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
> --
> http://mail.python.org/mailman/listinfo/python-list
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-list/attachments/20120419/0be8d544/attachment-0001.html>