Re: A case for real multiline comments
On 19Apr2012 15:13, Chris Angelico ros...@gmail.com wrote: | On Thu, Apr 19, 2012 at 2:29 PM, Cameron Simpson c...@zip.com.au wrote: | On 18Apr2012 22:07, Jordan Perr jor...@jperr.com wrote: | | I came across this case while debugging some Python code that contained an | | error stemming from the use of multiline strings as comments. The code | | contained a very long list of objects, and I had commented out some of the | | objects using the multiline string. | | You are aware that a string is not a comment? | | They're often (ab)used as comments, since Python lacks a multiline | comment facility. Even docstrings are really comments in disguise. 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. | I'd just do this: | | list = [ | Object1(arg), | ## Object2(arg), | ## Object3(arg), | Object4(arg) | ] | | Multiple lines of single line comments. Frankly, I find this much easier | to see (all the disabled lines are delineated with nice bright comment | markers, and the beginning and end of the comment (were it a multiline | comment) can't disappear off my screen. | | I would say you've made a case _against_ multiline coments. | | On the contrary, he has definitely made a case for multiline comments. 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? A multiline comment can just as easily be misused to similar effect: list = [ Object1(arg) /* bored now Object2(arg), Object3(arg), */ Object4(arg) ] 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. 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. | I like multiline comments, but they do have their associated problems, | most notably nesting. It gets quite awkward commenting out code that | searches for comment markers, too. | Perhaps what's needed is not a C-style /* */ comment marker, but | something which must always be on a line of its own, and can therefore | ONLY delimit entire-line comments. Something like what's often done | with a preprocessor #if 0 #endif pair. Which are also something of a pain to match up, leading to (hopefully correctly labelled) #endifs thus: #endif /* !FEATUREMACRO */ 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. | There's no way you can lose | the #endif at the end of a line, True. Cheers, -- Cameron Simpson c...@zip.com.au DoD#743 http://www.cskk.ezoshosting.com/cs/ It's better, when you're racing with someone you don't know so well, to stick to the inside line - it's easier to avoid the bits. - Barry Sheene, bike GP commentator -- http://mail.python.org/mailman/listinfo/python-list
Re: A case for real multiline comments
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
Re: A case for real multiline comments
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
Re: A case for real multiline comments
Chris Angelico wrote: [snip] Since Python doesn't have multiline comments, triple-quoted strings are sometimes pressed into service. [snip] Chris Angelico Let the triple quotes where they're meant to be. Use your text editor, any decent one will allow you to comment uncomment a block of code. JM -- http://mail.python.org/mailman/listinfo/python-list
Re: A case for real multiline comments
On Thu, Apr 19, 2012 at 8:17 PM, Alek Storm alek.st...@gmail.com wrote: 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. Certainly not. That completely ignores the whole point of this, which is to remove a block of lines without editing them all. Anyway, replace comment: with if 0: and you have it already. No, this is something that's parsed before indentation blocks are processed. ChrisA -- http://mail.python.org/mailman/listinfo/python-list
Re: A case for real multiline comments
On Thu, Apr 19, 2012 at 2:56 AM, Chris Angelico ros...@gmail.com wrote: 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. -8- 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? Two questions: Why don't you allow nested multiline comments? Many languages (e.g. ML, Scheme, Haskell, etc.) allow you to nest multi-line comments. It's mostly the C family of languages that refuse to do this, AFAIK. Least importantly: Why are multiline comments line-oriented? Why not inline, like with the C-style /* ... */ comments? This doesn't seem like a proper multiline comment. -- Devin -- http://mail.python.org/mailman/listinfo/python-list
Re: A case for real multiline comments
On Thu, Apr 19, 2012 at 10:15 PM, Devin Jeanpierre jeanpierr...@gmail.com wrote: Why don't you allow nested multiline comments? Many languages (e.g. ML, Scheme, Haskell, etc.) allow you to nest multi-line comments. It's mostly the C family of languages that refuse to do this, AFAIK. Allowing nesting or not allowing nesting is a design choice. If you write code that looks for the string /* or */ in a REXX program, you need to be careful in case it mis-nests (the usual recommendation is to use /||* instead of /* as a single literal). It makes no difference which way you choose, there's always issues to deal with. Least importantly: Why are multiline comments line-oriented? Why not inline, like with the C-style /* ... */ comments? This doesn't seem like a proper multiline comment. That thought was to avoid the complaint that you can easily lose the comment markers somewhere other than clearly at the beginning of the line. By demanding that they delimit entire lines, we avoid this. Of course, Python could choose to support /* */ comments instead/as well. ChrisA -- http://mail.python.org/mailman/listinfo/python-list
A case for real multiline comments
I came across this case while debugging some Python code that contained an error stemming from the use of multiline strings as comments. The code contained a very long list of objects, and I had commented out some of the objects using the multiline string. This caused a string to be appended to the list instead of ignoring the section. Consider the following code: list = [ Object1(arg), Object2(arg), Object3(arg), Object4(arg) ] Real multiline comments would produce [Object1, Object4]. The list, in fact, contains [Object1, Object2, Object3, Object4]. I can't really see a good way to get around this without true multiline comments. - Jordan -- http://mail.python.org/mailman/listinfo/python-list
Re: A case for real multiline comments
On 18Apr2012 22:07, Jordan Perr jor...@jperr.com wrote: | I came across this case while debugging some Python code that contained an | error stemming from the use of multiline strings as comments. The code | contained a very long list of objects, and I had commented out some of the | objects using the multiline string. You are aware that a string is not a comment? | This caused a string to be appended to | the list instead of ignoring the section. Consider the following code: | | list = [ | Object1(arg), | | Object2(arg), | Object3(arg), | | Object4(arg) | ] | | Real multiline comments would produce [Object1, Object4]. The list, in | fact, contains [Object1, Object2, Object3, Object4]. I can't really see a | good way to get around this without true multiline comments. I'd just do this: list = [ Object1(arg), ## Object2(arg), ## Object3(arg), Object4(arg) ] Multiple lines of single line comments. Frankly, I find this much easier to see (all the disabled lines are delineated with nice bright comment markers, and the beginning and end of the comment (were it a multiline comment) can't disappear off my screen. I would say you've made a case _against_ multiline coments. Cheers, -- Cameron Simpson c...@zip.com.au DoD#743 http://www.cskk.ezoshosting.com/cs/ Sam Jones samjo...@leo.unm.edu on the Nine Types of User: Frying Pan/Fire Tactician - It didn't work with the data set we had, so I fed in my aunt's recipe for key lime pie. Advantages: Will usually fix error. Disadvantages: 'Fix' is defined VERY loosely here. Symptoms: A tendancy to delete lines that get errors instead of fixing them. Real Case: One user complained that their program executed, but didn't do anything. The scon looked at it for twenty minutes before realizing that they'd commented out EVERY LINE. The user said, Well, that was the only way I could get it to compile. -- http://mail.python.org/mailman/listinfo/python-list
Re: A case for real multiline comments
On Thu, Apr 19, 2012 at 12:29 AM, Cameron Simpson c...@zip.com.au wrote: I'd just do this: list = [ Object1(arg), ## Object2(arg), ## Object3(arg), Object4(arg) ] Multiple lines of single line comments. Frankly, I find this much easier to see (all the disabled lines are delineated with nice bright comment markers, and the beginning and end of the comment (were it a multiline comment) can't disappear off my screen. My text editor just greys it out either way, so I don't get this readability argument. Does anyone use an editor that doesn't highlight comments appropriately? Fortunately, my editor can insert single-line comments in bulk, so multi-line comments aren't a big deal to me. I don't really get why Python doesn't have them, though. I would say you've made a case _against_ multiline coments. Could you explain how? -- Devin -- http://mail.python.org/mailman/listinfo/python-list
Re: A case for real multiline comments
On Thu, Apr 19, 2012 at 2:29 PM, Cameron Simpson c...@zip.com.au wrote: On 18Apr2012 22:07, Jordan Perr jor...@jperr.com wrote: | I came across this case while debugging some Python code that contained an | error stemming from the use of multiline strings as comments. The code | contained a very long list of objects, and I had commented out some of the | objects using the multiline string. You are aware that a string is not a comment? They're often (ab)used as comments, since Python lacks a multiline comment facility. Even docstrings are really comments in disguise. I'd just do this: list = [ Object1(arg), ## Object2(arg), ## Object3(arg), Object4(arg) ] Multiple lines of single line comments. Frankly, I find this much easier to see (all the disabled lines are delineated with nice bright comment markers, and the beginning and end of the comment (were it a multiline comment) can't disappear off my screen. I would say you've made a case _against_ multiline coments. On the contrary, he has definitely made a case for multiline comments. You just happen to disagree, and you prefer single line comments. :) I like multiline comments, but they do have their associated problems, most notably nesting. It gets quite awkward commenting out code that searches for comment markers, too. Perhaps what's needed is not a C-style /* */ comment marker, but something which must always be on a line of its own, and can therefore ONLY delimit entire-line comments. Something like what's often done with a preprocessor #if 0 #endif pair. There's no way you can lose the #endif at the end of a line, and editors can still syntax-highlight it (at least, SciTE does; haven't looked at many editors lately). It nests correctly, but can't ever mis-nest with a literal string. Thoughts? ChrisA -- http://mail.python.org/mailman/listinfo/python-list
