multiline comments

[StefanKarpinski]

Flagrantly stolen from CoffeeScript:

###
  This is a
  multiline comment
###

[StefanKarpinski]

The only issue this doesn't address is nesting, but here's an idea that addresses that too. What if the nesting is based on the indentation and number of # characters? As in they need to match up in order to be paired. Then you can do things like this:

###
function foo(x,y)
  ###
    There seems to be an odd bug in the following
    very complex code that I have yet to discover
  ###
  while x < y
    # ...
  end
end
###

Here, you can easily nest the inner multiline comment inside the function because it's indented, while the outer multiline comment that hides the function definition entirely is flush left.

#####
bar(x,y) = foo(x+y,y)

###
  Another multi-line comment
  that has no real content
###
baz(x,y) = foo(x,x+y)
#####

In this case, you have a multiline comment nested inside of another by using a different number of hash marks, allowing you to easily comment out blocks of code that already have multiline comments in them, just by using more hash marks.

I'm imagining that you would mostly use ### for normal inline multiline comments and #### and so on for commenting out blocks of code, but of course, that's a convention that's up to people coding. This just facilitates it.

Note that unlike /* ... */ style multiline comments, you don't need to keep track of balanced pairs to handle nesting correctly: all you need to do to find the correct closing pair is match indentation and number of #. Much simpler.

[JeffBezanson]

I dunno, I think this is harder to use because to comment out a region you have to look through to find the largest number of #'s and add 1. My guess is a pair of symmetric symbols is the easiest.

[ViralBShah]

Why can't we use /* ... */ for nested comments, or for that matter ### ... ### ? Couldn't this be handled just like nested blocks just as in the rest of the parser? Can't we just treat comments /* or ### as operators and comments as code? This could allow for other cool things later on as well.

[StefanKarpinski]

I'm adamantly against /* ... */ comments, and I'm still for the ### comments. I see Jeff's point, but I don't think it's that big a deal. Honestly, that's really an editor concern, and a pretty mild one at that. So your editor has to do a little more work, potentially. Whatever. For humans, I think this scheme is very usable and aesthetic. Either that or just no multiline comments at all, which, with decent editor support, is really no big deal.

[JeffBezanson]

I don't think we need any fancy features around comments. Comments are especially easy to parse, so it isn't too hard to write external tools to extract documentation.
I kind of like #| ... |# as a nod to lisp but I don't expect anybody else to appreciate that. I agree ### looks nice. But for now let's not do anything, and sleep on it a bit longer.

[StefanKarpinski]

Agreed. You can always add new comment styles (although ### comments are not strictly backwards compatible), but changing comment styles is much more disruptive. Definitely a v2.0 feature (if ever).

[StefanKarpinski]

Editors are good these days. Multiline comments aren't really necessary.

[benkehoe]

I am new to Julia, being made aware of it via Slashdot. It seems to me that closing this issue runs counter to your "Why We Created Julia" manifesto: you want to create a language that pleases everybody. "Editors are good these days" seems pretty cavalier for a fledgling language with this much promise; lack of multiline comments in LaTeX (and \begin{comment} doesn't count) is a source of much frustration for me, and a similar lack in Julia would be a barrier for me. IMO, the use case of quickly removing/re-adding a block of code during development greatly outweighs the potential breakage introduced by haphazard use, and has the added benefit of not repelling users exploring the language.

[StefanKarpinski]

We certainly never said that we "want to create a language that pleases everybody"; that's clearly impossible.

[benkehoe]

Let me restate it, then: you want to combine the best features of your favorite languages. The speed of C, the dynamism of Ruby, etc...and the lack of multiline comments of Python? I guess I just don't see the compelling reason for excluding them (if it's a lack of developer time/interest, shouldn't the feature request be left open?).

[JeffBezanson]

I'm not totally against this. I think we mostly haven't found a syntax for it we really like.
If we pick a syntax for this it should nest easily, since that seems to be the one feature people like in multiline comments.
Any suggestions, @benkehoe ?

The blog post takes a bit of artistic license...it's not meant to be a scientific paper. We're not literally as dynamic as ruby (or, of course, as fast as C in general, yet), and we also aren't just combining features of other languages.

[benkehoe]

I didn't mean to ascribe exact intentions to you in either of my comments, just the general idea that a good workhorse language should have multiline comments (and single-line comments, as C eventually took to heart after 20 years). It seems to me that if nesting is desired, the syntax should be something like /* ... */, that is, with distinct start and end markers. # should be involved since it's the "comment character". #| ... |# isn't terrible, though maybe brackets of some type would be better, either interior like #( ... )# or MATLAB-style #( ... #), though I guess you could run into trouble commenting out arguments or indexing.

[StefanKarpinski]

How about this:

#begin
  This is a comment.
#end

I still really like the original CoffeeScript-derived multiline comment scheme. If one requires both indentation and number of # chars to match, it's very nestable without requiring real parsing.

[benkehoe]

#begin/#end seems a lot of typing. I think ### is good, except for the nesting bit: none of the rest of the language is whitespace-aware, right? I don't mind non-nestable block comments, but as @JeffBezanson said that might be what people are looking for. The varying number (>=3) of # version would probably be easy to use if you left off the indentation part. What's wrong with #| ... |#?

[StefanKarpinski]

Every #x x# combo just looks weird to me. Try it on multiple lines:

#|
  comment here
|#

[lakewalker]

no mult line comment is fine, if very very want it, /* */ is just ok

[ViralBShah]

Of all the possibilities, I like ### the best.

[benkehoe]

@ViralBShah, do you mean non-nested? The other thing with indentation-nesting is that it breaks the ability of an editor to do auto-indenting of code. @StefanKarpinski, why would you need both indentation and number of characters to make parsing easy? Wouldn't number of characters be sufficient?

[JeffBezanson]

### does look nice. But if there can be any number of #'s, it prevents common forms of comment ASCII art :)
Maybe nesting isn't that important. We could start with ### and add the nesting version if it seems necessary. Or we could use ###{ }### for nesting; maybe if somebody really cares about nesting they won't mind the ugliness.

[benkehoe]

That seems quite reasonable.

[JeffreySarnoff]

(for your viewing pleasure)

If you choose to use tab character pairs for multiline comments, use tab pairs for nested multiline comments.
That decision parsimony offers user harmony. You should not care how relatively indented is the nested pair.

using treble octothorpe pairs

###
   one, two, three
   three twenty one
###

###
      # one, two, three 
      three twenty one
   ###
     one, two, three 
     three twenty one
   ###
###

using octothorpe vertical_bar pairings

#|
   one, two, three
   three twenty one
|#

#|
      # one, two, three 
      three twenty one
   #|
     one, two, three 
     three twenty one
   |#
|#

using octothorpe exclamation pairings

#!
   one, two, three
   three twenty one
!#

#!
      # one, two, three 
      three twenty one
   #!:
     one, two, three 
     three twenty one
   !#
!#

using octothorpe colon pairings

#:
   one, two, three
   three twenty one
:#

#:
      # one, two, three 
      three twenty one
   #:
     one, two, three 
     three twenty one
   :#
:#

[waldyrious]

I personally like the indented ### option best. Seems intuitive, easy to type, and symmetric. #begin / #end are good options too, as they would be neatly in line with the rest of the language's syntax, and would allow nesting without making it dependent on whitespace.

I dislike #( ... )# and similar options, since those break symmetry (as Stefan said, any #x ... x# construct looks much better inline than actually spanning multiple lines), and make it harder to toggle the multiline comments (the above options would simply require inserting/removing a space after the first # character to convert them into regular one-line comments).

[timholy]

FYI, the kate editor plugin can now "fold" comments bracketed by #BEGIN...#END (a suggestion from KDE folks). This choice could change, of course, and I like the lowercase. Meant to advertise/ask for input, but I've been too busy, so I guess this is the opportunity.

[jsarnoff]

I would rather #bgn .. #end (I find matching tag lengths makes visual scanning more pleasant).

Notwithstanding, I'd much prefer copying the way Julia demarks multiline comments :-)

[waldyrious]

While it'd be neat, other blocks don't match length with end. for, let and try happen to do so, but while, function, etc don't, so abbreviating to #bgn would break the current pattern.

[JeffreySarnoff]

true enough

I would be happy with having multiline comments as part of Julia with any
pairing.

begin ... end does not introduce a new scope -- presumably #begin .. *
#end* would not either. If it happens to be the case that treating multiline
comments as a distinct scope is helpful, then I would prefer #cmt* ... #*
end or (if keeping to the current token set matters) #let ... #end.

On Thu, Nov 1, 2012 at 6:28 PM, Waldir [email protected] wrote:

While it'd be neat, other blocks don't match length with end. for, letand
try happen to do so, but while, function, etc don't, so abbreviating to
#bgn would break the current pattern.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/69#issuecomment-9998478.

[hauptmech]

I was recently looking at multiline comments for a DSL. One issue I encountered was that when scanning through non-syntax highlighted code it help to have different opening an closing strings. In the end I used the following:

msg = "Hello."
----
Nesting is done using additional characters
---
I really don't have a complex code example to 
write but somehow I have lots of things to say about it.
===
====
println(msg)

[simleb]

Some thoughts:

One issue that can arise with ### is when you have 3 layers of single line comments, which I would qualify as not frequent but still happening sometimes:

# foo()
## for i = 1:3
###     baz() # Hu-ho, where is the closing symbol?
##     buzz()
## end

---

Paradoxically, multiline comments are often useful on a single line like this:

f(x, /* y, */ z) // I want to try f without this argument... quick and dirty
f(/* unused */ x, y) // inlined comment

You could also do it with a single line comment:

f(x,
#  y,
  z)
f(x, # unused
  y)

but the first approach can sometimes be useful.

---

I think the pair #(#-#)# would be quite neat. Demo:

f(x, #(# y, #)# z)

foo()
#(#
for i = 1:3
  #(#
     baz()
     baz2()
  #)#
     buzz()
end
#)#

Benefits:

• the # character makes it look like a comment
• parentheses make obvious and concise opening and closing symbols
• the last # character makes it look better (quasi-symetric) especially when written on its own line
• since opening and closing symbols are different, they should be easy to parse and nesting can be allowed

[StefanKarpinski]

This is the worst feature ever.

[EconometricsBySimulation]

Please consider that block commenting might be valuable within code blocks:
foo(x,y) = foo1(x) #|foo1 does ... |# + foo2(y) #|foo2 does ... |#

I know it looks silly but it might be useful. If that is the case then making it a two character set is ideal. The look of the lisp comment #| Your boxed in comment |# is pretty great to me. I have programmed and commented extensively with Stata which uses /* ... */ and I find it ugly and non-intuitive. Perhaps to the detriment of my code, but for the sake of readability, I go out of my way in Stata, not to use block commenting because I find it so ugly.

[XilinJia]

Just searching on how to to what EconometricsBySimulation mentioned. It is very cumbersome to do some code testing without block comment.

[kmsquire]

See #6128. #= and =# have been added as block comment delimiters in v0.3.

[esd100]

I think @simleb suggestion was by far the best of every single one on this thread.

I think the pair #(# comment #)# would be quite neat.

Benefits:

• the # character makes it look like a comment
• parentheses make obvious and concise opening and closing symbols
• the last # character makes it look better (quasi-symetric) especially when written on its own line
  since opening and closing symbols are different, they should be easy to parse and nesting can be allowed

[StefanKarpinski]

The ship has sailed on this issue – that's why it's closed.

[ashleylid]

Either I am going crazy or #= =# doesnt work in jupyter. Not that I like using jupyter, but I cant get my Juno / Sublime install to work - but I digress.

When building a function is there a way to have multiline comments that work the same way as help function and print out the necassary? And if using jupyter how?

[KristofferC]

Multiline comments work in jupyter but the syntax highlighting doesn't.

[ashleylid]

@KristofferC

[KristofferC]

Exactly

[ashleylid]

right then

EDIT: the more I think about it, the less necessary this seems. Considering its really just using Markdown. Was just a habit.

[stevengj]

Jupyter would need a patch to the Julia codemirror mode. (I don't think it was a high priority since multiline comments are rarely used interactively. They are mostly for commenting out large blocks in a file.) cc @malmaud

[malmaud]

Correct. I don't think this is something I could get around to for a while though.

[jpvee]

How is nesting line and multi-line comments supposed to work? Currently (0.5.0) the following code is valid:

##=

However, "wrapping" it inside a multi-line comment produces invalid code:

#= ##= =#

Is this really the intended behavior?

[stevengj]

Probably #= ##= =# should be valid; should be a straightforward parser patch. Can you file an issue?

Multiline comments are our favorite thing to work on in the parser, and a key feature of Julia overall, so I'm sure @JeffBezanson will jump at this chance to further improve them. 😉

[jpvee]

Oh, I could have filed an issue, but I'm not even sure that the code should be valid in the first place.
I was just curious and trying to find out whether it should be possible to nest comments of different types.

In particular: Should a line comment be a line comment within a multi-line comment? And should a multi-line comment be a multi-line comment within a line-comment? My personal gut feeling would answer "no" in both cases because otherwise you are likely to run into problems of "overlapping ranges" which is certainly a Bad Thing (correct me if I'm wrong - perhaps there's a way of preventing this).

In that case, the second hash in the code would not start a line comment but be just some character with no special meaning whereas the second #= would open a nested multi-line comment (BTW, that name is quite unfortunate since a multi-line comment is obviously not required to span multiple lines; IMHO "block comment" would have been a better choice) which would be closed by the terminating =#, thus leaving the "outer" multi-line comment unclosed. So, Julia would be quite correct in rejecting the code.

So, I repeat my question: Is there an "official opinion" on how to treat nested comments of different types?

[JeffreySarnoff]

#= is intended to open a comment that may, but need not, span more than one line.
=# is intended to close a comment opened with #=
#= and =# are paired, and pairs are nestable
[letting one =# close all arbitrarily nested open comment blocks was considered and set aside]

#= .. =# should behave the same whether or not any inline comment characters # appear before, between, after .. or in any other dispersional riff (as I recall).

this should parse as a comment,
right now it does not
(if you PR, please include this)

   #=# comment #=#

[StefanKarpinski]

Sigh, can we just delete this feature?

[KristofferC]

During my 2 ½ years of Julia I have basically never seen a complaint about this. Just forget it exist?

[StefanKarpinski]

I would but people keep commenting on this issue.

[malmaud]

Multiline comments are generally useful though. Since the syntax isn't ingrained yet, it would still be easy to deprecate it for something better.

…

On Fri, Mar 10, 2017 at 10:25 AM Stefan Karpinski ***@***.***> wrote: I would but people keep commenting on this issue. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#69 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AA8SvRthejzfJrysM9UaBlX437A65el7ks5rkWt-gaJpZM4AF2X9> .

[tknopp]

I use multiline comments and think they are very useful.

[JeffreySarnoff]

@StefanKarpinski We require interspersable annotation. Tapestry is code.

Our octothorpe has been more octo than thorpe, three of a kind rather than one kind of three.

# remains the mark where <comment> follows [or continues were it already #-following] through eol.

For commentary and temporary code isolation, the pair-surrounded commentary context ignores any #s and eols. These comment contexts sequence, nest and unwind like parentheses. I think there remains only one conflict free and easy to see ASCII alternative.

[=

function ab(a, b)
    return a^b / b^a
end

=]