[Python-ideas] Multi-line comment blocks.

[Guido van Rossum]

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 at 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 at python.org> wrote:
>>
>> On Fri, Jun 15, 2012 at 3:47 PM, David Gates <gatesda at 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 at 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 at python.org
>> >> http://mail.python.org/mailman/listinfo/python-ideas
>> >
>> >
>> >
>> > _______________________________________________
>> > Python-ideas mailing list
>> > Python-ideas at python.org
>> > http://mail.python.org/mailman/listinfo/python-ideas
>> >
>>
>>
>>
>> --
>> --Guido van Rossum (python.org/~guido)
>
>



-- 
--Guido van Rossum (python.org/~guido)