On Thu, Apr 19, 2012 at 4:04 PM, Cameron Simpson <c...@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 -- http://mail.python.org/mailman/listinfo/python-list
