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.