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 <ros...@gmail.com> wrote: > 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. > > 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 >
-- http://mail.python.org/mailman/listinfo/python-list