The comment block for Python

Ideas
22

I’d go for <<< … >>>, feels much easier to get which are the opening and the closing ones.

1 Like
23

If I’m not mistaken, the second line will undo the effect of the first line, no? If you want to manipulate lines with sed, you should use markers in your comments:

#:section 1
blah blah
#:end
##:section 2
#blah blah
##:end

Then you can use

sed -i '/:section 1/,/:end/s/^/#/' file.py
sed -i '/:section 2/,/:end/s/^#//' file.py

to swap which part is commented out. No changes to Python needed, it works now. Plus, you have readable labels to the sections.

Manipulating Python code with sed is a very unusual use-case, but it’s one that today’s Python is already accommodating.

2 Likes
24

That looks quite confusing to read. You need to take notice of exactly
how many #s there are to tell which parts are active. – but only on
lines where the # is followed by “”". No longer can you just skim and
ignore any line that starts with #.

Also it’s rather specialised, allowing you to toggle between 2 versions,
but not choose one of 3 or more.

1 Like
25 
def verify(filename, clear_payload):
    #"""
    # I would like to verify if the PNG is valid and not corrupt but Pillow .verify() is not yet implemented
    im = Image.open(filename)
    im.verify()
    im.close()
    #"""
    content = open(filename, "rb").read()

This is actually not a totally uncommon pattern; the code snippet can be “deactivated” by one keystroke:

def verify(filename, clear_payload):
    """
    # I would like to verify if the PNG is valid and not corrupt but Pillow .verify() is not yet implemented
    im = Image.open(filename)
    im.verify()
    im.close()
    #"""
    content = open(filename, "rb").read()

This turns these few lines into a multi-line string literal that is just discarded. This construct can be (ab)used as a multi-line comment. (In this particular case, it is a doc string, but maybe the author did not care about this.)

1 Like
26

I don’t see what’s so anti-Python about /* */ when Python already borrowed a good number of syntaxes from C++. To me that’s the most natural choice if we are to add a multiline comment syntax to Python. The fact that it’s an outright invalid syntax in Python today also makes it more viable than your proposed syntax.

27

Here is a related idea. I find the following more useful than a proposed comment block alone, but I probably wouldn’t propose it outside of this topic.

  • triple quoted h-string (Inspired by shell heredoc):
h"""somename

# this string can contain other triple-quote strings
# because its endquote is marked with 'somename'

def commented_out_function():
    """
    docstring
    """
    return

"""somename
  • n-string (noop)
    It’s a string that is thrown away by the parser and because of that it doesn’t have
    to follow indentation rules.
def func(a, b):
    x = a * b
n"""
    # I'm not here, this is not happening
    print(a, b, x)
"""

Each of them could be sometimes useful on its own. And combined into a nh-string they form a universal comment block.

4 Likes
29

So why not just use this?

"""
comment block
"""

The IDE recognizes this (as same as Function’s Documention).

2 Likes
30

What is that? The same as the first post?

1 Like
31

Only problem is that >>> is used in docstrings to indicate the REPL. If tools then evaluate the code in a docstring (which a few testing tools do), that would likely raise a syntax error, resulting in breaking tests?!

1 Like
32

I like the heredoc string. It is loosely reminiscent of Rust raw string literals, but much more readable because the delimiters are on their own lines and can serve a documentation purpose like a small comment already. Maybe you can propose it in a separate thread.

33

Oh yeah - nothing like conflicting with git conflict markers themselves. That would be astonishing!

3 Likes