multiline comments: #= ... =#

[StefanKarpinski]

This is a shameless rip-off of @stevengj's multiline comment p.r. – because I really like #= ... =# better :-)

[stevengj]

Great, now we have to follow discussions in three issues and two PRs.

[stevengj]

• Editor brace matching is a huge usability advantage, not to be discarded lightly.
• I'm not convinced that one version is aesthetically so much nicer than the other.
• Even if #= ... =# looks a bit nicer, I'm not sure that looks are so important here. Multiline comments are mainly useful for quick debugging hacks to comment out large blocks of code. We should really encourage people to continue to use a uniform style of # .... for permanent multiline documentation. (In which case ugly multiline comments are a feature, not a bug.)

[StefanKarpinski]

There's a tradition for all multiline comment discussions to be a complete disaster.

[StefanKarpinski]

Honestly, I'm ok with your PR too, I just wanted to put an alternative out there as well. If we're going to do #{ ... }# perhaps we should allow #( ... )# and #[ ... ]# too, which makes nesting easier.

[quinnj]

But will editor's automatically match the } and #? It seems like you're only getting the single } matched and you still have to add the terminating # manually anyway.
In sublime, however, this distinction is arbitrary because it's a one-line addition to the Comments.tmPreferences file to specify multi-line comments, then selected text is easily commented out by using the ctrl+shift+/.

[jiahao]

We may have to put this to a vote à la kittenwar.

[stevengj]

@karbarcca, I'm not concerned about whether you have to type the # manually. By "brace matching" I mean that when you place the cursor at } the editor will highlight the matching { for you, taking into account arbitrary levels of nesting for you, and the editor will allow you to jump from { to } or vice versa.

(And yes, some editors are programmable enough that they could be programmed to do something like brace matching for #= ... =#, but this can't compare to having it work out-of-the-box with virtually all programming editors with the existing brace-matching interface.)

[stevengj]

@StefanKarpinski, I think it would be crazy to introduce multiple multiline-comment syntaxes. Pascal has both (* ... *) and { ... } for legacy reasons and this has always been considered a mess as far as I know.

The current proposals already support nesting. And with brace matching, it is easy to figure out which nested braces go together.

[quinnj]

Ah, that makes sense. Thanks.

[StefanKarpinski]

In that case, I'd mildly prefer #( ... )# since it's easier to type.

[jakebolewski]

And so the insanity begins again...

[stevengj]

Why is #( easier to type? Both { and ( are shift-key combinations.

My reasoning for { over ( is that I want to minimize the chance that the user was intending to insert a single # to make a single-line comment but accidentally starts a multiline comment instead. ( is used much more often than { in Julia (almost 10 times as often in Base, for example). { and [ are used about equally often in Base, but my intuitive sense was that you are more likely to comment out a #[ some array....] than a foo#{T}(x....).

Furthermore, #( would be a problem for any documentation containing parenthetical remarks. e.g.

#Some comment
#(which I thought was a good idea).

at which point the parser barfs. Similarly (to a lesser degree) for #[. In contrast, { is barely used in English writing.

[stevengj]

The good news is that there are rational criteria here which have nothing to do with personal tastes.

[StefanKarpinski]

I find #( easier to type because they're on the same keyboard row (the number row), whereas typing #{ involves finding two keys while holding shift that are far apart and on different rows. But perhaps that's an argument in favor of #{ in light of the "hard to type by accident" criterion.

[stevengj]

I'm not so much worried about typing #? by accident, regardless of what ? we choose. I'm worried about someone who types # intentionally to begin a one-line comment, and the comment happens to start with (.

Of course, any practical #? sequence would run some risk of such accidents, because Julia already uses all reasonable punctuation characters. And accidentally beginning a multiline comment is only an annoyance, not a disaster, since the parser will tell you what happened. But I think we should make a reasonable effort to minimize the chance of such accidents, and a don't use parentheses at the beginning of a documentation line rule would be a neverending trap for the unwary.

(Also, as a touch-typist I think you have a strange notion of what is easy to type. But we all know that you are twisted, Stefan. In any case, if you don't like typing { then Julia may be the wrong language for you. :-) )

[pao]

if you don't like typing { then Julia may be the wrong language for you. :-) )

To the contrary, I think it explains exactly why Julia is not in the curly-brace language family. You type a lot more blocks than Any-typed array literals.

[stevengj]

@pao, actually, if you grep the Base source code, [ and { are used about equally often, mostly for type parameterization rather than Any[] literals.

(Even if that weren't true, and it probably isn't true for interactive use, the fact remains that typing { for type parameters etcetera will inevitably be far more common than #{ multiline comments if we encourage # ... for permanent documentation. And in any case the difficulty of { is not a substantial objection as far I can tell; in comparison to # and ( the difference is marginal at best.)

[StefanKarpinski]

Ok, I for one am convinced by these arguments that #{ ... }# is a good choice and the least likely to cause problems.

[stevengj]

Okay, in that case closing this issue so that technical implementation discussions can continue at #6128.

[pao]

@pao, actually, if you grep the Base source code, [ and { are used about equally often, mostly for type parameterization rather than Any[] literals.

I didn't realize you were going to take me so seriously; it was certainly not intended as direct comment on this issue. Sorry about that. (I forgot about type parameters; they kind of blend into the syntax.)