Yet Another Multiline Comment Proposal

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.

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

-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.

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.

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.

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

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

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.

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 :smiley:

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

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

-1 on any multiline comment proposal.

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.

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.