[Python-ideas] Multi-line comment blocks.

[Bruce Leban]

On Jun 15, 2012 4:46 PM, "Carl Meyer" <carl@
<carl at oddbird.net>oddbird.net<carl at 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 at gmail.com>
@ <jeanpierreda at gmail.com>gmail.com <jeanpierreda at 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20120615/f5dd21b5/attachment.html>