Yet Another Multiline Comment Proposal

[Marco_Sulla]

I know that Python does not support multi-line comments, because they can render the code unreadable. I have a proposal that could fix this problem.

Consider this code:

a = (1, 4, 7)

for x in a:
    print(x)

for i, y in enumerate(a):
    print("{}: {}".format(i+1, y))

I decide to comment the first for loop. Well, I could do this:

a = (1, 4, 7)

/*
TODO  fix it before restore it

for x in a:
    print(x)
*/

for i, y in enumerate(a):
    print("{}: {}".format(i+1, y))

Notice that:

1. a blank line is required before /* and after */, and a newline character is required after /* and before */. (edit: only space and tabs are allowes after /* and */)
2. /* and */ are at the same level of the code (edit: and the level must be the lowest column of the commented block). For example, you can’t do this:

a = (1, 4, 7)

for x in a:
    print(x)
    
    /*
    print(x*x)

for i, y in enumerate(a):
    print("{}: {}".format(i+1, y))
*/

EDIT: but you can do this:

a = (1, 4, 7)

for x in a:
    print(x)
    
/*
    print(x*x)

for i, y in enumerate(a):
    print("{}: {}".format(i+1, y))
*/

I think in this way a coder can use a multiline comment that is readable, without using the ugly trick of using the multistring…

PS: I must say I preferred to use ###, but it’s not retro-compatible.

[Rhodri (Rhodri James)]

-1. It’s still much too easy to read the unadorned lines of code as actual code.

[mjpieters (Martijn Pieters)]

-1 on this, both because I am not convinced there is a need, at all, and because your proposed syntax rules make no sense and are really ugly. Why do you feel this is needed at all?

Your proposed syntax doesn’t add anything, really, and is not more readable. In fact, you demonstrated that the syntax is not intuitive either, because you use /* ... */ in your example but then switch to talk about \* and */ in your post. I’m assuming you meant to echo the C-family of /* ... */ multi-line comments.

Next, the restrictions to have to place the marks at the same indentation level and the newline requirements feel arbitrary. What do these restrictions prevent? E.g. why would the following not be acceptable?

a = (1, 4, 7)
/*  disabled this section for now
for x in a:
    print(x)
*/
for i, y in enumerate(a):
    print("{}: {}".format(i+1, y))

The /* and */ markers are unambiguously denoting a multi-line block, so why the requirement to use blank lines? Why the requirement to use a newline right after /*?

The indentation requirement isn’t clear either. If you are going to disable a series of lines, then just disabled the lines between start and end, regardless of indentation. E.g. why make the following illegal?

a = (1, 4, 7)

for x in a:
    print(x)
    
/*
    print(x*x)

for i, y in enumerate(a):
    print("{}: {}".format(i+1, y))
*/

With all these extra syntax rules, what you achieve is that anyone with only a passing familiarity with Python but a lot of experience with C-style block comments will be thoroughly confused by the restrictions. I’d much rather we’d use a different style altogether, like #{ ... }#. IF this was something Python developers need.

[Marco_Sulla]

@mjpieters

Next, the restrictions to have to place the marks at the same indentation level and the newline requirements feel arbitrary. What do these restrictions prevent?

Prevent this:

/*for x in a:
    print(x)*/

that is IMHO less readable. I can agree that maybe the newline before and after are a bit too much, but not this requirement.

@mjpieters

The indentation requirement isn’t clear either. If you are going to disable a series of lines, then just disabled the lines between start and end, regardless of indentation.

I think I can agree, since you can do this with normal comments. But in this case IMHO /* and */ should be on the same column, and this column must be the lowest column of the commented block lines.

@mjpieters

I’d much rather we’d use a different style altogether, like #{ ... }#

You can’t use #, because is not retro-compatible.

[mjpieters (Martijn Pieters)]

@Marco_Sulla

I think I can agree, since you can do this with normal comments. But in this case IMHO /* and */ should be on the same column, and this column must be the lowest column of the commented block lines.

But why do you think this needs to be the case? What problems do you foresee if you don’t set this restriction?

@Marco_Sulla

I’d much rather we’d use a different style altogether, like #{ ... }#

You can’t use # , because is not retro-compatible.

My point was more that if you are going to deviate from the established pattern of how the /* ... */ syntax is used in several other, popular languages, that you shoudn’t use that syntax at all but rather would use something different.

[Marco_Sulla]

@Rhodri

It’s still much too easy to read the unadorned lines of code as actual code.

Well, it’s much more harder, since /* and */ are on their own lines, must be aligned and must be at the lowest column of the commented block, to be more evident (this answer your question, @mjpieters?).

For example, IMHO is more readable than:

a = (1, 4, 7)

#for x in a:
 #   print(x)

for i, y in enumerate(a):
    print("{}: {}".format(i+1, y))

PS: I edited the first post. I think the newline after and before the comment block is matter of the irreprehensible PEP 8.

PPS: @mjpieters: I agree Python can’t use /**/, but I can’t think about a valid substitute at the moment

[Marco_Sulla]

Excuse me for the spam: what about ***?

[zware (Zachary Ware)]

At that point, why not just use '''? Or better yet, a VCS

-1 on any multiline comment proposal.

[Rhodri (Rhodri James)]

@Marco_Sulla

For example, IMHO is more readable than:

a = (1, 4, 7)

#for x in a:
 #   print(x)

With all due respect, I think even that misaligned hash version is more obviously commented out than using /*…*/. And I say that as someone who is primarily a C programmer.

[Marco_Sulla]

@zware

At that point, why not just use ''' ?

I quote myself:

I think in this way a coder can use a multiline comment that is readable, without using the ugly trick of using the multistring

Anyway, +1 for VCS.

@Rhodri: I’m quite sure that also the more newbie programmer has at least an editor with syntax coloring… and if you think about using vi without syntax coloring, well, I can say that the major problem with Python without a decent editor is the mandatory indentation. Yes, I edited a py code with vi without syntax coloring, so I can speak for experience.

I like very much mandatory indentation, I think it’s a optimum idea, but objectively renders the life of a sysop without a decent vi or nano really hard. So IMHO the fact that the code could have multi-line comments that are arguably less readable, I think is the last of their problems.

[dg-pb]

I think this is worth exploring.

1. It already exists in C, so not re-inventing anything, and minimizing learning cost
2. This would potentially provide performance benefits as parser can skip it altogether without AST or subsequent string initialization.
3. In the long run could adopt multi-line comment standard. E.g. markdown or rst, so that IDEs can apply appropriate syntax highlighting for inner code and patterns.

Strong +1 for testing the waters for this again.

Related:

• I think this is better than Comment string literals (c-strings) - #36 by Nineteendo

[zware (Zachary Ware)]

The issues with this proposal have already been enumerated, and the topic was dropped without support 5 years ago.

Many of my opinions have changed in the last 5 years, this one has not.

[MegaIng (Cornelius Krupp)]

@dg-pb

It already exists in C, so not re-inventing anything, and minimizing learning cost

This assumes that people already know other languages. Since python is a first language for many people, this is IMO a wrong assumption.

@dg-pb

This would potentially provide performance benefits as parser can skip it altogether without AST or subsequent string initialization.

Really?

• This at best can have an effect when parsing the code - which happens rarely in all normal python programs
• The effect compared to a string literal is minimal. A single expression statement’s cost is going to be completely trivial compared basically every other possible statement. And if this is a performance bottleneck for some reason, I am sure we can find optimization within existing syntax
• The increased complexity of the lexer (which is always going to be the case) might offset whatever benefit we gain. Sure I doubt this, but it’s just as justified as your claim.

@dg-pb

In the long run could adopt multi-line comment standard. E.g. markdown or rst, so that IDEs can apply appropriate syntax highlighting for inner code and patterns.

If we don’t do this immediately it has zero benefit in this regard to using comments as multiline comments. And if we do it immediately, it has zero benefits without some kind of enforcement. And syntax restrictions on comments seems counterproductive. (and e.g. PyCharm can already highlight the content of string literals as markdown or rst if requested)

---

Now to my actual counter arguments. The /**/ syntax is terrible.

1. It overloads already used operator symbols in completely new and incompatible ways (no, I don’t count familiar with other languages as a valid argument)
2. It can’t actually be freely applied to existing code if that code contains */ either because it already contains a multiline comment or because that is a combination contained with a string. ^[1]

General arguments against all possible new multiline comment syntax.:

3. It would be an almost completely duplicate of existing multiline string syntax. And the new stuff that would be made possible (like comments in the middle of a line/logical statement) are terrible things to do.
4. It would be a massive amount of churn for all parsers, and in contrast to a few other syntax changes, also all highlighters.

And again, you didn’t list any usecases where existing solutions clearly fail. IMO, get a non-trivial IDE and use a “comment this lines” shortcut is a way better solution almost always.

(and yes, IMO, other languages are also wrong to include multiline comments. But other languages that aren’t whitespace sensitive like python at least have valid excuses that end-of-line comments don’t quite fullfil all niches)

---

1. Note that a possible idea is to allow the comments to be nested with regard to matched up /* and */ pairs. However, this massively complicates lexing again for very little benefit, and doesn’t solve the issue with it already appearing inside of strings. ↩︎