Multi-line comment blocks.
Multi-line strings as comments don't nest, don't play well with docstrings, and are counter-intuitive when there's special language support for single-line comments. Python should only have one obvious way to do things, and Python has two ways to comment, only one of which is obvious. My suggestion is to add language support for comment blocks, using Python's existing comment delimiter: # Single-line comment #: Multi-line comment #: Nested multi-line comments work perfectly Of course they do, they're just nested blocks def foo(): """Docstrings work perfectly. Why wouldn't they?""" pass # No need for an end-delimiter like """ or */
On 6/15/12 9:49 AM, David Gates wrote:
Multi-line strings as comments don't nest, don't play well with docstrings, and are counter-intuitive when there's special language support for single-line comments. Python should only have one obvious way to do things, and Python has two ways to comment, only one of which is obvious.
Multi-line string literals aren't comments. They are multi-line string literals. Unlike a comment, which does not show up in the compiled bytecode, the Python interpreter actually does something with those string literals. Sometimes people abuse them as ways to poorly emulate block comments, but this is an abuse, not a feature of the language.
My suggestion is to add language support for comment blocks, using Python's existing comment delimiter:
# Single-line comment #: Multi-line comment #: Nested multi-line comments work perfectly Of course they do, they're just nested blocks def foo(): """Docstrings work perfectly. Why wouldn't they?""" pass # No need for an end-delimiter like """ or */
The main problem is that #: currently has a meaning as a line comment. This could break existing code. -- Robert Kern "I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco
Robert Kern schrieb am Fri, 15. Jun 2012, um 10:50:40 +0100:
Multi-line string literals aren't comments. They are multi-line string literals. Unlike a comment, which does not show up in the compiled bytecode, the Python interpreter actually does something with those string literals. Sometimes people abuse them as ways to poorly emulate block comments, but this is an abuse, not a feature of the language.
Multi-line string literals do not generate code in CPython, and their use as comments has BDFL approval: https://twitter.com/gvanrossum/status/112670605505077248 (I don't use them as comments either, and rather rely on my editor for commenting blocks.) Cheers, Sven
On 6/15/12 11:49 AM, Sven Marnach wrote:
Robert Kern schrieb am Fri, 15. Jun 2012, um 10:50:40 +0100:
Multi-line string literals aren't comments. They are multi-line string literals. Unlike a comment, which does not show up in the compiled bytecode, the Python interpreter actually does something with those string literals. Sometimes people abuse them as ways to poorly emulate block comments, but this is an abuse, not a feature of the language.
Multi-line string literals do not generate code in CPython, and their use as comments has BDFL approval:
Well fancy that. -- Robert Kern "I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco
I agree that using multi-line strings as literals comes across as an ugly hack, even if it is BDFL-approved. Your other point is valid, though as far as I can tell it's only an issue when the comment is indented less than it ought to be (and starts with "#:", of course): #: Valid either way. The next line has the #: same level of indentation, so it's not #: counted as part of the block. print('a') # Causes an IndentationError in existing code. #: print('b') def foo(): #: This one would break. print('c') On Fri, Jun 15, 2012 at 8:04 AM, Robert Kern <robert.kern@gmail.com> wrote:
On 6/15/12 11:49 AM, Sven Marnach wrote:
Robert Kern schrieb am Fri, 15. Jun 2012, um 10:50:40 +0100:
Multi-line string literals aren't comments. They are multi-line string literals. Unlike a comment, which does not show up in the compiled bytecode, the Python interpreter actually does something with those string literals. Sometimes people abuse them as ways to poorly emulate block comments, but this is an abuse, not a feature of the language.
Multi-line string literals do not generate code in CPython, and their use as comments has BDFL approval:
Well fancy that.
-- Robert Kern
"I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco
_______________________________________________ Python-ideas mailing list Python-ideas@python.org http://mail.python.org/mailman/listinfo/python-ideas
Let's not try to design a syntax for multi-line comments. There are already enough ways to emulate them. Designing a new syntax based on # plus some special character is doomed for backwards compatibility (never mind the clever tricks proposed). --Guido On Fri, Jun 15, 2012 at 9:23 AM, David Gates <gatesda@gmail.com> wrote:
I agree that using multi-line strings as literals comes across as an ugly hack, even if it is BDFL-approved.
Your other point is valid, though as far as I can tell it's only an issue when the comment is indented less than it ought to be (and starts with "#:", of course):
#: Valid either way. The next line has the #: same level of indentation, so it's not #: counted as part of the block. print('a')
# Causes an IndentationError in existing code. #: print('b')
def foo(): #: This one would break. print('c')
On Fri, Jun 15, 2012 at 8:04 AM, Robert Kern <robert.kern@gmail.com> wrote:
On 6/15/12 11:49 AM, Sven Marnach wrote:
Robert Kern schrieb am Fri, 15. Jun 2012, um 10:50:40 +0100:
Multi-line string literals aren't comments. They are multi-line string literals. Unlike a comment, which does not show up in the compiled bytecode, the Python interpreter actually does something with those string literals. Sometimes people abuse them as ways to poorly emulate block comments, but this is an abuse, not a feature of the language.
Multi-line string literals do not generate code in CPython, and their use as comments has BDFL approval:
Well fancy that.
-- Robert Kern
"I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco
_______________________________________________ Python-ideas mailing list Python-ideas@python.org http://mail.python.org/mailman/listinfo/python-ideas
_______________________________________________ Python-ideas mailing list Python-ideas@python.org http://mail.python.org/mailman/listinfo/python-ideas
-- --Guido van Rossum (python.org/~guido)
On Fri, 15 Jun 2012 02:49:18 -0600 David Gates <gatesda@gmail.com> wrote:
Multi-line strings as comments don't nest, don't play well with docstrings, and are counter-intuitive when there's special language support for single-line comments. Python should only have one obvious way to do things, and Python has two ways to comment, only one of which is obvious. My suggestion is to add language support for comment blocks, using Python's existing comment delimiter:
Any decent text editor has a way to comment and uncomment whole blocks of text (in Kate, it is Ctrl+D IIRC). Regards Antoine.
David Gates wrote:
Multi-line strings as comments don't nest, don't play well with docstrings, and are counter-intuitive when there's special language support for single-line comments. Python should only have one obvious way to do things,
That's not what the Zen says. The zen says: There should be one-- and preferably only one --obvious way to do it. which is a positive statement that there should be an obvious way to solve problems, NOT a negative statement that there shouldn't be non-obvious ways.
and Python has two ways to comment, only one of which is obvious. My suggestion is to add language support for comment blocks, using Python's existing comment delimiter:
There is already support for nested multi-line comments: the humble # symbol can be nested arbitrarily deep. All you need is a modern editor that understands Python syntax, and with a single command you can comment or uncomment a block: # This is a commented line. # def fun(a, b, c): # """Docstrings are fine when commented""" # pass # # This is a nested comment. # And no need for an end-delimiter either. If your editor is old or too basic, you can do it by hand, which is a pain, but doable. Python doesn't need dedicated syntax to make up for the limitations of your editor. Don't complicate the language for the sake of those poor fools stuck using Notepad. -- Steven
My proposal wasn't for people who hand-code the single-line comment syntax but for those that use multi-line string comments. Since the multi-line string hack's BDFL-approved, people will use it and other people will have to deal with it. The best alternative would be official discouragement of multi-line string comments. It's fine if Python doesn't have an officially-sanctioned multi-line comment syntax, but if it's going to have one, it should have one that makes sense. On Fri, Jun 15, 2012 at 4:12 PM, Steven D'Aprano <steve@pearwood.info>wrote:
David Gates wrote:
Multi-line strings as comments don't nest, don't play well with docstrings, and are counter-intuitive when there's special language support for single-line comments. Python should only have one obvious way to do things,
That's not what the Zen says. The zen says:
There should be one-- and preferably only one --obvious way to do it.
which is a positive statement that there should be an obvious way to solve problems, NOT a negative statement that there shouldn't be non-obvious ways.
and Python has two ways to comment, only one of which is obvious. My
suggestion is to add language support for comment blocks, using Python's existing comment delimiter:
There is already support for nested multi-line comments: the humble # symbol can be nested arbitrarily deep. All you need is a modern editor that understands Python syntax, and with a single command you can comment or uncomment a block:
# This is a commented line.
# def fun(a, b, c): # """Docstrings are fine when commented""" # pass # # This is a nested comment. # And no need for an end-delimiter either.
If your editor is old or too basic, you can do it by hand, which is a pain, but doable.
Python doesn't need dedicated syntax to make up for the limitations of your editor. Don't complicate the language for the sake of those poor fools stuck using Notepad.
-- Steven _______________________________________________ Python-ideas mailing list Python-ideas@python.org http://mail.python.org/mailman/listinfo/python-ideas
On Fri, Jun 15, 2012 at 3:47 PM, David Gates <gatesda@gmail.com> wrote:
My proposal wasn't for people who hand-code the single-line comment syntax but for those that use multi-line string comments. Since the multi-line string hack's BDFL-approved, people will use it and other people will have to deal with it.
What's wrong with it?
The best alternative would be official discouragement of multi-line string comments. It's fine if Python doesn't have an officially-sanctioned multi-line comment syntax, but if it's going to have one, it should have one that makes sense.
What doesn't make sense about it? --Guido
On Fri, Jun 15, 2012 at 4:12 PM, Steven D'Aprano <steve@pearwood.info> wrote:
David Gates wrote:
Multi-line strings as comments don't nest, don't play well with docstrings, and are counter-intuitive when there's special language support for single-line comments. Python should only have one obvious way to do things,
That's not what the Zen says. The zen says:
There should be one-- and preferably only one --obvious way to do it.
which is a positive statement that there should be an obvious way to solve problems, NOT a negative statement that there shouldn't be non-obvious ways.
and Python has two ways to comment, only one of which is obvious. My suggestion is to add language support for comment blocks, using Python's existing comment delimiter:
There is already support for nested multi-line comments: the humble # symbol can be nested arbitrarily deep. All you need is a modern editor that understands Python syntax, and with a single command you can comment or uncomment a block:
# This is a commented line.
# def fun(a, b, c): # """Docstrings are fine when commented""" # pass # # This is a nested comment. # And no need for an end-delimiter either.
If your editor is old or too basic, you can do it by hand, which is a pain, but doable.
Python doesn't need dedicated syntax to make up for the limitations of your editor. Don't complicate the language for the sake of those poor fools stuck using Notepad.
-- Steven _______________________________________________ Python-ideas mailing list Python-ideas@python.org http://mail.python.org/mailman/listinfo/python-ideas
_______________________________________________ Python-ideas mailing list Python-ideas@python.org http://mail.python.org/mailman/listinfo/python-ideas
-- --Guido van Rossum (python.org/~guido)
On 06/15/2012 04:51 PM, Guido van Rossum wrote:
On Fri, Jun 15, 2012 at 3:47 PM, David Gates <gatesda@gmail.com> wrote:
My proposal wasn't for people who hand-code the single-line comment syntax but for those that use multi-line string comments. Since the multi-line string hack's BDFL-approved, people will use it and other people will have to deal with it.
What's wrong with it?
The reason I discourage using multi-line strings as comments is that they don't nest (which I think David mentioned earlier). If you've got a short multi-line-string-as-comment in the middle of a function, and then you try to use multi-line-string technique to comment out that entire function, you don't get what you want, you get a syntax error as your short comment is now parsed as code. (FWIW, I don't think this means Python needs a dedicated syntax for multi-line comments, I think multiple lines beginning with # works just fine.) Carl
On Fri, Jun 15, 2012 at 4:07 PM, Carl Meyer <carl@oddbird.net> wrote:
On 06/15/2012 04:51 PM, Guido van Rossum wrote:
On Fri, Jun 15, 2012 at 3:47 PM, David Gates <gatesda@gmail.com> wrote:
My proposal wasn't for people who hand-code the single-line comment syntax but for those that use multi-line string comments. Since the multi-line string hack's BDFL-approved, people will use it and other people will have to deal with it.
What's wrong with it?
The reason I discourage using multi-line strings as comments is that they don't nest (which I think David mentioned earlier). If you've got a short multi-line-string-as-comment in the middle of a function, and then you try to use multi-line-string technique to comment out that entire function, you don't get what you want, you get a syntax error as your short comment is now parsed as code.
(FWIW, I don't think this means Python needs a dedicated syntax for multi-line comments, I think multiple lines beginning with # works just fine.)
In which languages do multi-line comments nest? AFAIK not in the Java/C/C++/JavaScript family. -- --Guido van Rossum (python.org/~guido)
Perl, Ruby, Lisps, OCaml, F#, Haskell, and I believe Pascal. There are probably others. None of these use significant indentation; they're just smart enough to not ignore beginning delimiters within multi-line comments. On Fri, Jun 15, 2012 at 5:47 PM, Guido van Rossum <guido@python.org> wrote:
On Fri, Jun 15, 2012 at 4:07 PM, Carl Meyer <carl@oddbird.net> wrote:
On 06/15/2012 04:51 PM, Guido van Rossum wrote:
On Fri, Jun 15, 2012 at 3:47 PM, David Gates <gatesda@gmail.com> wrote:
My proposal wasn't for people who hand-code the single-line comment syntax but for those that use multi-line string comments. Since the multi-line string hack's BDFL-approved, people will use it and other people will have to deal with it.
What's wrong with it?
The reason I discourage using multi-line strings as comments is that they don't nest (which I think David mentioned earlier). If you've got a short multi-line-string-as-comment in the middle of a function, and then you try to use multi-line-string technique to comment out that entire function, you don't get what you want, you get a syntax error as your short comment is now parsed as code.
(FWIW, I don't think this means Python needs a dedicated syntax for multi-line comments, I think multiple lines beginning with # works just fine.)
In which languages do multi-line comments nest? AFAIK not in the Java/C/C++/JavaScript family.
-- --Guido van Rossum (python.org/~guido) _______________________________________________ Python-ideas mailing list Python-ideas@python.org http://mail.python.org/mailman/listinfo/python-ideas
On 16/06/2012 01:28, David Gates wrote:
Perl, Ruby, Lisps, OCaml, F#, Haskell, and I believe Pascal. There are probably others. None of these use significant indentation; they're just smart enough to not ignore beginning delimiters within multi-line comments.
In Pascal, comments start with "{" or "(*" and end with "}" or "*)". How do you write a nested comment in Perl? As far as I'm aware, it doesn't have nested comments either.
A Perl nested comment: =for Comment =for Nested comment =cut =cut On Fri, Jun 15, 2012 at 6:47 PM, MRAB <python@mrabarnett.plus.com> wrote:
On 16/06/2012 01:28, David Gates wrote:
Perl, Ruby, Lisps, OCaml, F#, Haskell, and I believe Pascal. There are probably others. None of these use significant indentation; they're just smart enough to not ignore beginning delimiters within multi-line comments.
In Pascal, comments start with "{" or "(*" and end with "}" or "*)".
How do you write a nested comment in Perl? As far as I'm aware, it doesn't have nested comments either.
_______________________________________________ Python-ideas mailing list Python-ideas@python.org http://mail.python.org/mailman/listinfo/python-ideas
On 16 June 2012 02:00, David Gates <gatesda@gmail.com> wrote:
A Perl nested comment:
=for Comment =for Nested comment =cut =cut
And the irony is that, as far as I recall, this is a form of Perl's embedded documentation syntax (and hence very similar in spirit to using multiline strings as comments). See http://www.perl6.org/archive//rfc/5.html (and note that perl 6 does *not*, apparently, include multiline comments). Paul.
I was throwing together a quick language list, so I pulled some of them from hyperpolyglot, including Perl. So, guess it's not a dedicated comment syntax, but it does nest (the document you linked says it doesn't, but it's outdated). Found out that Lua also uses dead-code strings as comments. It supports nested strings, but the delimiters in each layer must be distinct. Trying to nest them otherwise is a syntax error, so you can't accidentally end a string early like you can with quote delimiters. On Sat, Jun 16, 2012 at 2:56 AM, Paul Moore <p.f.moore@gmail.com> wrote:
On 16 June 2012 02:00, David Gates <gatesda@gmail.com> wrote:
A Perl nested comment:
=for Comment =for Nested comment =cut =cut
And the irony is that, as far as I recall, this is a form of Perl's embedded documentation syntax (and hence very similar in spirit to using multiline strings as comments). See http://www.perl6.org/archive//rfc/5.html (and note that perl 6 does *not*, apparently, include multiline comments).
Paul.
Please stop this discussion. Python is not going to change this. -- --Guido van Rossum (python.org/~guido)
On Jun 15, 2012 4:46 PM, "Carl Meyer" <carl@ <carl@oddbird.net>oddbird.net<carl@oddbird.net>> wrote:
The reason I discourage using multi-line strings as comments is that they don't nest (which I think David mentioned earlier). If you've got a short multi-line-string-as-comment in the middle of a function, and then you try to use multi-line-string technique to comment out that entire function, you don't get what you want, you get a syntax error as your short comment is now parsed as code.
I think "commenting out" code and writing true comments are different functions. I would not advocate multi line strings for commenting out but they work very well for long text comments. Nested #s and a modern editor work well enough for commenting out IMHO and are much harder to not notice. --- Bruce (from my phone) On Jun 15, 2012 7:28 PM, "Devin Jeanpierre" <jeanpierreda<jeanpierreda@gmail.com> @ <jeanpierreda@gmail.com>gmail.com <jeanpierreda@gmail.com>> wrote:
the reason that multiline comments are so great is that they can go virtually anywhere without too much concern. For example:
def foo(a, b(*=None*)): ...
In this hypothetical code, I commented out the =None in order to run the test suite and see if any of my code omitted that argument, maybe to judge how reasonable it is to remove the default. Here, neither "#" comments nor docstrings really make this easy. The closest equivalent is:
def foo(a, b): #=None): ...
And that has to be done entirely by hand, and might be especially painful (involving copy-paste) if it isn't the last argument that's being changed.
For commenting out part of a line I think best practice is duplicating the entire line as a comment and editing it directly. That handles scenarios that inline comments don't and more importantly ensures reverting is error free. # def foo(a, b=None): def foo(a, b=[]):
Python tool world seems to think that strings that aren't inside an expression are "docstrings", not comments, and you have to be careful to avoid being misinterpreted by your tools, which is unfortunate.
Agreed. But even if multiline/inline comments were added you'd still have that problem, right? --- Bruce
On Fri, Jun 15, 2012 at 11:26 PM, Bruce Leban <bruce@leapyear.org> wrote:
For commenting out part of a line I think best practice is duplicating the entire line as a comment and editing it directly. That handles scenarios that inline comments don't and more importantly ensures reverting is error free.
I suppose so. So far I've done pretty much exactly what I wrote, and used the undo buffer for safety. There are also things like commenting out values inside lists and such, but these are much less common for me. Like, definitely inline comments are more flexible than EOL comments, but finding compelling use-cases is kinda hard. There's only a bunch of minor special cases and annoyances, as far as I can see.
Python tool world seems to think that strings that aren't inside an expression are "docstrings", not comments, and you have to be careful to avoid being misinterpreted by your tools, which is unfortunate.
Agreed. But even if multiline/inline comments were added you'd still have that problem, right?
I don't see why this problem would exist for comments. Comments do not have a (common) culture or behaviour of meaning anything else other than comments, whereas triple-quoted strings have three purposes: - Actual string objects - Docstrings - Comments Multiline comments would need a lot of time to accumulate that many orthogonal uses, and one would hope that they never do. Aside from that, most of these sorts of tools manipulate code either after parsing or after executing, and by then all comments have been discarded. They wouldn't even see multiline comments. Although, it's worth mentioning that doctest is an interesting exception to all this: it uses regexps to parse out comments, which are used as directives for the test runner. However, doctest only touches code that is explicitly meant to be touched by doctest, and that code generally doesn't need comments at all. -- Devin
On Fri, Jun 15, 2012 at 8:48 PM, Devin Jeanpierre <jeanpierreda@gmail.com>wrote:
For commenting out part of a line I think best practice is duplicating
On Fri, Jun 15, 2012 at 11:26 PM, Bruce Leban <bruce@leapyear.org> wrote: the
entire line as a comment and editing it directly. That handles scenarios that inline comments don't and more importantly ensures reverting is error free.
I suppose so. So far I've done pretty much exactly what I wrote, and used the undo buffer for safety.
Undo is dangerous because in most editors it will undo other intervening changes to other parts of the program. You make a change like this to find a bug, then find and fix the bug. Undo will remove the fix.
Agreed. But even if multiline/inline comments were added you'd still have
that problem, right?
I don't see why this problem would exist for comments. Comments do not have a (common) culture or behaviour of meaning anything else other than comments, whereas triple-quoted strings have three purposes:
I meant that even if new comment syntax were added, string-style comments wouldn't be going away anytime soon. There's a high bar for adding features and an even higher bar for removing them. So tools will need handle the current string comments for quite a while as well as being modified to parse any new comment syntax. --- Bruce Follow me: http://www.twitter.com/Vroo http://www.vroospeak.com
On Sat, Jun 16, 2012 at 12:28 AM, Bruce Leban <bruce@leapyear.org> wrote:
I meant that even if new comment syntax were added, string-style comments wouldn't be going away anytime soon. There's a high bar for adding features and an even higher bar for removing them. So tools will need handle the current string comments for quite a while as well as being modified to parse any new comment syntax.
Sorry, I didn't understand your point at first. That's a concern. Although I'm not sure it pans out -- do any tools handle string comments? I only know of tools ignoring them or mistreating them, not handling them specially. -- Devin
Devin Jeanpierre writes:
[T]riple-quoted strings have three purposes:
- Actual string objects - Docstrings
Docstrings are a subset of "actual string objects," of course. They just have a special syntax, and their primary use is "meta" (eg, introspection).
- Comments
And so are strings-as-comments. Strings could be used as comments in C: void foo () { "This comment would be optimized away, most likely."; "Not to mention compilers may bitch about lack of effect."; return 42; } It's just a side effect of expression statements. You don't have to like it, of course.
Devin Jeanpierre wrote:
Although, it's worth mentioning that doctest is an interesting exception to all this: it uses regexps to parse out comments, which are used as directives for the test runner. However, doctest only touches code that is explicitly meant to be touched by doctest,
The normal way of running doctest is to use implicit test discovery: you point doctest at a module, and it will discover your doctests without you needing to explicitly list them. That's why there is a doctest directive to *disable* tests, but no directive to enable them: you only need to explicitly turn tests off, not turn them on.
and that code generally doesn't need comments at all.
I write many functions or classes that include both documentation in the docstring, including doctests, and implementation comments in the body of the function. Docstrings and comments in the body of a function have very different purposes, just because a function has one doesn't mean that it won't have the other. -- Steven
On Sat, Jun 16, 2012 at 2:53 AM, Steven D'Aprano <steve@pearwood.info> wrote: <SNIP> Steven, the code I was talking about was the code inside the doctests, not the code surrounding the doctests. So, for example, whether or not the body of the function has comments doesn't matter. They could never be confused with doctest directives. -- Devin
Carl Meyer writes:
The reason I discourage using multi-line strings as comments is that they don't nest (which I think David mentioned earlier).
I don't see that as a problem. While I don't use multiline strings as comments myself, I wouldn't object to others using them for commentary, especially given the syntactic analogy to docstrings. But for commenting out code, a nice heavy line in the left margin is an appropriate marker, and would certainly "discuss" the matter with colleagues who disabled large chunks of code with paired delimiters, whether primarily string or comment delimiters. I'm a big non-fan of preprocessor conditional compilation directives, for that matter. (Sure, your editor can mark or hide them, and it's not like you can avoid them in languages like C, but that doesn't mean I have to *like* them.) So IMO the current syntax encourages good style.
Carl Meyer wrote:
The reason I discourage using multi-line strings as comments is that they don't nest (which I think David mentioned earlier). If you've got a short multi-line-string-as-comment in the middle of a function, and then you try to use multi-line-string technique to comment out that entire function, you don't get what you want, you get a syntax error as your short comment is now parsed as code.
You can nest two such string-comments, by using different string delimiters: '''Outermost comment def func(x, y): """Innermost comment or docstring goes here """ pass If you regularly need to do this, you're doing it wrong. You should be deleting unused code, not commenting it out. Nested comments as change tracking is *worse* than no change tracking, in my opinion. '''
(FWIW, I don't think this means Python needs a dedicated syntax for multi-line comments, I think multiple lines beginning with # works just fine.)
Agreed. -- Steven
On discussions I've seen, including in this very thread ( http://mail.python.org/pipermail/python-ideas/2012-June/015544.html ), there are inevitably people that think the multi-line string comment syntax is non-Pythonic, confusing, and/or a bad practice. While they can adapt to it, the initial impression is often that it's an overly-clever hack. String literals *work* as comments in other languages, but the idiomatic usage is always the dedicated comment syntax (even if there isn't a multi-line syntax) because people assume that uncommented code is active and significant. The same goes for other tricks that use dead code as comments, such as the "if false:" block I've seen suggested as an alternative. Comments do more than just delimit non-code: they signal developer intent. On Fri, Jun 15, 2012 at 4:51 PM, Guido van Rossum <guido@python.org> wrote:
On Fri, Jun 15, 2012 at 3:47 PM, David Gates <gatesda@gmail.com> wrote:
My proposal wasn't for people who hand-code the single-line comment syntax but for those that use multi-line string comments. Since the multi-line string hack's BDFL-approved, people will use it and other people will have to deal with it.
What's wrong with it?
The best alternative would be official discouragement of multi-line string comments. It's fine if Python doesn't have an officially-sanctioned multi-line comment syntax, but if it's going to have one, it should have one that makes sense.
What doesn't make sense about it?
--Guido
On Fri, Jun 15, 2012 at 4:12 PM, Steven D'Aprano <steve@pearwood.info> wrote:
David Gates wrote:
Multi-line strings as comments don't nest, don't play well with docstrings, and are counter-intuitive when there's special language support for single-line comments. Python should only have one obvious way to do things,
That's not what the Zen says. The zen says:
There should be one-- and preferably only one --obvious way to do it.
which is a positive statement that there should be an obvious way to
problems, NOT a negative statement that there shouldn't be non-obvious ways.
and Python has two ways to comment, only one of which is obvious. My suggestion is to add language support for comment blocks, using Python's existing comment delimiter:
There is already support for nested multi-line comments: the humble # symbol can be nested arbitrarily deep. All you need is a modern editor
solve that
understands Python syntax, and with a single command you can comment or uncomment a block:
# This is a commented line.
# def fun(a, b, c): # """Docstrings are fine when commented""" # pass # # This is a nested comment. # And no need for an end-delimiter either.
If your editor is old or too basic, you can do it by hand, which is a pain, but doable.
Python doesn't need dedicated syntax to make up for the limitations of your editor. Don't complicate the language for the sake of those poor fools stuck using Notepad.
-- Steven _______________________________________________ Python-ideas mailing list Python-ideas@python.org http://mail.python.org/mailman/listinfo/python-ideas
_______________________________________________ Python-ideas mailing list Python-ideas@python.org http://mail.python.org/mailman/listinfo/python-ideas
-- --Guido van Rossum (python.org/~guido)
You can never get agreement on what is Pythonic or not, that's why we have a BDFL. Feel free not to use strings as comments; as noted the multi-line # form is fine. Do note that Python has docstrings, so strings used as comments aren't completely alien like they would be in most languages. On Fri, Jun 15, 2012 at 4:33 PM, David Gates <gatesda@gmail.com> wrote:
On discussions I've seen, including in this very thread ( http://mail.python.org/pipermail/python-ideas/2012-June/015544.html ), there are inevitably people that think the multi-line string comment syntax is non-Pythonic, confusing, and/or a bad practice. While they can adapt to it, the initial impression is often that it's an overly-clever hack.
String literals work as comments in other languages, but the idiomatic usage is always the dedicated comment syntax (even if there isn't a multi-line syntax) because people assume that uncommented code is active and significant. The same goes for other tricks that use dead code as comments, such as the "if false:" block I've seen suggested as an alternative. Comments do more than just delimit non-code: they signal developer intent.
On Fri, Jun 15, 2012 at 4:51 PM, Guido van Rossum <guido@python.org> wrote:
On Fri, Jun 15, 2012 at 3:47 PM, David Gates <gatesda@gmail.com> wrote:
My proposal wasn't for people who hand-code the single-line comment syntax but for those that use multi-line string comments. Since the multi-line string hack's BDFL-approved, people will use it and other people will have to deal with it.
What's wrong with it?
The best alternative would be official discouragement of multi-line string comments. It's fine if Python doesn't have an officially-sanctioned multi-line comment syntax, but if it's going to have one, it should have one that makes sense.
What doesn't make sense about it?
--Guido
On Fri, Jun 15, 2012 at 4:12 PM, Steven D'Aprano <steve@pearwood.info> wrote:
David Gates wrote:
Multi-line strings as comments don't nest, don't play well with docstrings, and are counter-intuitive when there's special language support for single-line comments. Python should only have one obvious way to do things,
That's not what the Zen says. The zen says:
There should be one-- and preferably only one --obvious way to do it.
which is a positive statement that there should be an obvious way to solve problems, NOT a negative statement that there shouldn't be non-obvious ways.
and Python has two ways to comment, only one of which is obvious. My suggestion is to add language support for comment blocks, using Python's existing comment delimiter:
There is already support for nested multi-line comments: the humble # symbol can be nested arbitrarily deep. All you need is a modern editor that understands Python syntax, and with a single command you can comment or uncomment a block:
# This is a commented line.
# def fun(a, b, c): # """Docstrings are fine when commented""" # pass # # This is a nested comment. # And no need for an end-delimiter either.
If your editor is old or too basic, you can do it by hand, which is a pain, but doable.
Python doesn't need dedicated syntax to make up for the limitations of your editor. Don't complicate the language for the sake of those poor fools stuck using Notepad.
-- Steven _______________________________________________ Python-ideas mailing list Python-ideas@python.org http://mail.python.org/mailman/listinfo/python-ideas
_______________________________________________ Python-ideas mailing list Python-ideas@python.org http://mail.python.org/mailman/listinfo/python-ideas
-- --Guido van Rossum (python.org/~guido)
-- --Guido van Rossum (python.org/~guido)
On Fri, Jun 15, 2012 at 6:51 PM, Guido van Rossum <guido@python.org> wrote:
On Fri, Jun 15, 2012 at 3:47 PM, David Gates <gatesda@gmail.com> wrote:
My proposal wasn't for people who hand-code the single-line comment syntax but for those that use multi-line string comments. Since the multi-line string hack's BDFL-approved, people will use it and other people will have to deal with it.
What's wrong with it?
It behaves "badly" in a lot of circumstances. If you put it in an expression, it's treated as a string (not as an invisible thing) (IMHO this is its worst failing, the rest is just fluff). And to add on some more reasons, if you put it at the top of a file, class statement, or def statement, it's treated as a docstring, which may accidentally be included in autogenerated docs. In fact, for some common tools (epydoc), even if you put it in some other places it may be grabbed as a docstring (e.g. if you put it after a variable definition inside a class statement), and be included in the documentation. Basically the Python tool world seems to think that strings that aren't inside an expression are "docstrings", not comments, and you have to be careful to avoid being misinterpreted by your tools, which is unfortunate. In contrast, the reason that multiline comments are so great is that they can go virtually anywhere without too much concern. For example: def foo(a, b(*=None*)): ... In this hypothetical code, I commented out the =None in order to run the test suite and see if any of my code omitted that argument, maybe to judge how reasonable it is to remove the default. Here, neither "#" comments nor docstrings really make this easy. The closest equivalent is: def foo(a, b): #=None): ... And that has to be done entirely by hand, and might be especially painful (involving copy-paste) if it isn't the last argument that's being changed. I have done this sort of thing (commenting out stuff inside def statements) many times, I don't even remember why. It crops up. Of course, multiline comments go anywhere, not just in def statements. And they span multiple lines! In practice, most of the time that's just as easy with the editor key that inserts "#", I just wanted to point out a case where no existing solution makes it so easy. -- Devin
Devin Jeanpierre wrote:
In contrast, the reason that multiline comments are so great is that they can go virtually anywhere without too much concern. For example:
def foo(a, b(*=None*)): ...
So now you're changing the semantics from *multiline* to *embedded* comments. Being able to embed a comment within an expression is a very different thing from just having comments extend across multiple lines.
In this hypothetical code, I commented out the =None in order to run the test suite and see if any of my code omitted that argument, maybe to judge how reasonable it is to remove the default. Here, neither "#" comments nor docstrings really make this easy. The closest equivalent is:
def foo(a, b): #=None): ...
The simplest change here would be to just delete the "=None", run your tests, then put it back if the tests fail. Of course, alternatives are the comment above, or perhaps even better: #def foo(a, b=None): def foo(a, b): ... which avoids the risk of forgetting what change needs to be undone. In any case, all these alternatives are so trivial that they are hardly an argument for adding new comment syntax.
And that has to be done entirely by hand, and might be especially painful (involving copy-paste) if it isn't the last argument that's being changed.
"Especially painful"? I fear you exaggerate somewhat. -- Steven
participants (13)
-
Antoine Pitrou -
Bruce Leban -
Carl Meyer -
David Gates -
Devin Jeanpierre -
Greg Ewing -
Guido van Rossum -
MRAB -
Paul Moore -
Robert Kern -
Stephen J. Turnbull -
Steven D'Aprano -
Sven Marnach