Julia: 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/JuliaLang/julia/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

[JeffreySarnoff]

Jeff's initial preference is fine by me.
#| ... |#

If the choice between a pairing of 3-chars and a pairing of 2-chars, I
prefer the less visually intrusive.

On Fri, Nov 30, 2012 at 7:32 PM, Simon Leblanc [email protected]:

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

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

[JeffBezanson]

I will say that if I were to add this, the only thing I'd consider is something like #| |# or #( )#, since they nest and don't conflict with ASCII art made of #, which must be supported :)

[StefanKarpinski]

This is the biggest bikeshed ever.

[JeffreySarnoff]

Of the two, #( )# is easier to type (less hand movement).

On Fri, Nov 30, 2012 at 8:26 PM, Jeff Bezanson [email protected]:

I will say that if I were to add this, the only thing I'd consider is
something like #| |# or #( )#, since they nest and don't conflict with
ASCII art made of #, which must be supported :)

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

[JeffBezanson]

It is something of a language design tradition to have incredibly long debates over the syntax of comments :)

[waldyrious]

#| and |# would be especially interesting if we could do #|# for a "self-contained" comment. That would allow toggling comments by typing (or erasing) only two characters.

inline comment:
f(x, #| y, |# z)
deactivated inline comment:
f(x, #|# y, #|# z)

multiline comment:

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

deactivated multiline comment:

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

by the way, other symmetrical characters could be interesting, such as : (which I find more visually appealing) or * (which borrows from the // and /* ... */ model)

[StefanKarpinski]

Actually, I kind of like this:

#=
  Comment here
=#

Feels slightly inspired by POD and plays well with ASCII art, e.g. #========. We could allow #=# as a self-closing comment.

[toivoh]

On Dec 1, 2012 7:05 PM, "Stefan Karpinski" [email protected] wrote:

Actually, I kind of like this:

=

Comment here
=#

Feels slightly inspired by POD and plays well with ASCII art, e.g.

========. We could allow #=# as a self-closing comment.

+1

[johnmyleswhite]

+1 for the PHP-ification of Julia's comments.

[StefanKarpinski]

What is PHP-ification? Does PHP do this for multiline comments?

Incidental question. If you want to have multiline comments, presumably part of the purpose is to be able to comment out arbitrary chunks of code. That fails if you have a closing comment character in a string or trailing comment. If we make comments nestable, then opening comments in strings and trailing comments are also an issue. Example:

#=
"=#"
# =#
=#

So the question is how syntax-aware do we make out multiline comments? My inclination is to make it rather aware so that all these things "just work", but that's certainy much more complicated.

[JeffreySarnoff]

or its juila-set inspired version :~)

~

  comment here

~#

allowing #~# as a self-closing comment

On Sat, Dec 1, 2012 at 1:09 PM, John Myles White
[email protected]:

+1 for the PHP-ification of Julia's comments.

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

[johnmyleswhite]

PHP doesn't do this with comments. I was just commenting on the visual similarity to PHP style HTML templates with <%= =%> entries.

[StefanKarpinski]

Right, right. I do really rather like #= ... =# which is odd because it seems like I hate most multiline comment proposals for some reason.

[ViralBShah]

I must say that of all the alternatives I have seen, I like #= ... =# the most.

[JeffreySarnoff]

=

 well, wrap me up in
 #=  and call me  =#
 comfortably swathed

=#

On Sat, Dec 1, 2012 at 9:43 PM, Viral B. Shah [email protected]:

I must say that of all the alternatives I have seen, I like #= ... =# the
most.

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

[staticfloat]

@StefanKarpinski; is it a problem to have the parser figure out what is a string before it figures out what is a comment opener/closer?

[StefanKarpinski]

It's doable, but it's a little weird because it means that strings inside of comments would be meaningful. So you are kind of parsing the contents of comments. Come to think of it maybe this should be integrated with doc stringish functionality.

[svaksha]

= =# reminds me of the extra effort (read, limbs and think emacs) it requires, as opposed to say, the simple prime ''' symbol: http://en.wikipedia.org/wiki/Prime_%28symbol%29#Use_in_mathematics.2C_statistics.2C_and_science

What would be the pitfalls of using ''' ''' as a docstring?

[ggggggggg]

I don't care much what format is used, but I want to put in a vote for multi-line comments. Though their use as docstrings seems like it will be hard since so many julia methods are defined as special cases of other methods like f(a,b,c) = f((a,b), d(c))

[ivarne]

What about using an empty @comment begin ..... end macro for multiline comments?

macro comment(b) end

The problem is that the comment block needs to be syntactically correct, but that is fine if you want to ignore part of your code for testing.

[lsorber]

How about unifying single-line and block comments. The comment character #can be used to indicate the start of both types of comments, and results in a single-line comment if it is not followed by a termination tag, e.g., /#.

Examples:

# This is a single-line comment.

# This is a block comment,
  consisting of two lines. /#

# Block comments are a useful tool
foo(a, #b,/# c)

Advantages are that it does not depend on whitespace, which is consistent with the rest of Julia, it allows for nested comments, and its unified nature allows you to efficiently comment a whole code block by typing two characters. For example:

# This is an example code block
foo()
bar()

is quickly nullified by

# This is an example code block
foo()
bar() /#

[bsilbaugh]

It seems that multi-line comments are typically used for one of two reasons:
case 1: Code documentation
case 2: Blanking out code blocks

In regards to case 1, perhaps it's best to choose a syntax that you know will be document generator friendly, or provide a dedicated mechanism like Python doc strings. (I actually favour the latter, but that's just my opinion.)

In regards to use case 2, should this usage really be encouraged? We have version control, which allows a person to delete code blocks, carefully document why they did it, and then revert that action if need be. We have macros, which can potentially enable/disable debugging mechanisms like assertions and print statements more elegantly than multi line comments.

[thomasmcoffee]

Python provides two different mechanisms for these two cases:

1. string literal expressions for code documentation, which can be multi-line with triple quotes (""" or ''')
2. # for blanking out code blocks, which cannot be multi-line (but are easily done in blocks by editors)

This approach has advantages for each case:

1. documentation strings are visually distinct from commented code, especially with syntax highlighting
2. it is very visually obvious what code is blanked out, even without syntax highlighting

It's okay to use a symmetric operator """ for multi-line docstrings, since they need not be nested.

If an asymmetric operator for multi-line comments is really desired, I recommend something whose directionality is visually very obvious: it is not for #| |# or #= =#, but is for <# #>.

I would choose <# #> over #( )# or (# #) since parentheses have their own matchfix meaning, and could be visually interpreted as separate.

<#
  function foo(n)
  """
  foo docstring
  """
    # return 1    # blanked out
    "returns zero"
    return 0
  end
#>

If ordinary string literals "..." are allowed as docstrings, the user would need to avoid making them the last expression in a function (hence the return value). Since most docstrings refer to the code following, this restriction seems fine, and keeps all behavior consistent.

[JeffBezanson]

<# is the identifier < followed by a line comment, so that won't work. I would say something like #= =# is reasonably intuitive, since that way all comments start with #.

[StefanKarpinski]

The intuitiveness of <# is debatable – I read that as the closing marker of the pair, as in #> comment <# – which would actually work as a comment delimiter pair. Still like #= comment =# best though.

[thomasmcoffee]

The closing end of #| |# also starts with an identifier, but I was assuming special parsing for comments.

The directional ambiguity of <# #> had not occurred to me. I can't think of another clearly directional QWERTY symbol that is not already used in matchfix syntax, so perhaps it rests there.

For the record, I am not convinced that multi-line comments are a good idea at all, given advantage 2 mentioned above. Python seems to be cleaner without them.

[johnmyleswhite]

But Python has docstrings, which are basically like multiline comments. The non-locality that I personally dislike about multiline comments is replicated by docstrings.

[StefanKarpinski]

I've always felt that doc strings in python are a bit off. Why can't I just have a string in void context? That's a perfectly valid expression, albeit one of limited utility. There are also a bunch of problematic issues that don't crop up in Python that do crop up in Julia, which is much more liberal with strings – like Ruby or Perl:

• What happens if there's interpolation inside a doc string?
• What if that interpolation has side effects?
• What if the interpolation depends on function arguments?
• How do you evaluate the doc string without values for the argument?
• Or is it just a string in void context and not a doc if it contains no interpolations?
• Or is it an error to have interpolation in something that could be interpreted as a doc string?
• What if the doc string is the last expression in the function?
• Does that mean I can't implicitly return a multi-line string using interpolation?

These don't come up in Python because Python doesn't have interpolation and requires explicit returns.

function imamonster!(arg)
  """
  imamonster! – $(arg)!
  $(println("Hello, world."))
  """
end

If you want inline documentation there's really no advantage of stealing a valid expression form over using a particular comment convention. If you use a comment convention, then at least if you're unaware of the convention, you won't interpret anything wrong, you just won't be aware of the documentation.

[StefanKarpinski]

@johnmyleswhite – can you elaborate on the non-locality issue?

[thomasmcoffee]

To me, non-locality seems okay for docstrings because (a) the reader can easily distinguish them from code, and (b) they are not nested. Just looking at them, the reader knows they are never executed, and can visually see what such region they belong to.

Non-locality is a problem with multi-line commented code, because just looking at a line of code does not tell you whether it is executed or not, nor what such region it belongs to.

[johnmyleswhite]

Stefan, non-locality just means that you can't parse a single line without seeing something that might have happened hundreds of lines earlier. This happens a lot in libraries for Python, where the docstrings extend for many pages.

Thomas, you're definitely right: it is possible for most lines to determine that they're not code, although the occasional example that slips into a docstring will sometimes break this. The thing that drives me nuts is that the docstrings introduce a region with ad hoc whitespace, which makes it really hard to manipulate them using things like multicursors.

Anyway, enough people want multiline comments (which have this weird interpretation problem) that we should just pick a sane delimiter and implement them.

[StefanKarpinski]

Just looking at them, the reader knows they are never executed,

How is that? A string is a perfectly valid expression in Julia with a valid value that results when it is executed. That's also true in Python, btw, which is why I've always thought doc strings were a bit sketchy.

[StefanKarpinski]

The closing end of #| |# also starts with an identifier, but I was assuming special parsing for comments.

The closing end starting with an identifier isn't an issue – it's the opening end that it's a problem for.

[thomasmcoffee]

A string is a perfectly valid expression in Julia with a valid value that results when it is executed. That's also true in Python

I believe the Python compiler optimizes away lone string literals, thus they are effectively absent.

If you use a comment convention, then at least if you're unaware of the convention, you won't interpret anything wrong, you just won't be aware of the documentation.

Maybe I misunderstand, but I would have said the opposite: if you use string literals as docstrings, then (except for the last-expression-in-a-function case) you will interpret the program correctly even if you are unaware of the convention, while being unaware of the documentation. If you use additional syntax, you must be aware of it to interpret the program correctly.

The closing end starting with an identifier isn't an issue

As I say, I was considering this from the perspective of usability and readability, assuming the parser would treat these combinations specially. If a line of code ended with the identifier |, starting a single-line comment immediately after would look like the closing |#.

[StefanKarpinski]

What the compiler does or doesn't optimizes away is irrelevant to the language semantics – otherwise it wouldn't be an optimization, it would be a semantically significant part of the language.

What I meant was that if literate documentation is provided as a special type of comment, such as:

# foo(x) – compute the foo transform of `x`
#
function foo(x)
  # do stuff
end

For example, let's say the convention is that comments that lead right up to a function or method definition are associated with them as documentation, then this data clearly does not affect execution since even if you know nothing about doc comments, this is still clearly a comment.

Anyway, Python doc strings are a non-starter for Julia because of all the issues I listed above.

[bsilbaugh]

The Linux kernel coding style document (https://www.kernel.org/doc/Documentation/CodingStyle) states that the preferred style for long (multi-line) comments is:

/*
 * This is the preferred style for multi-line
 * comments in the Linux kernel source code.
 * Please use it consistently.
 *
 * Description:  A column of asterisks on the left side,
 * with beginning and ending almost-blank lines. 
 */

I've also seen this in many other C and C++ projects. I seem to recall reading a C++ style guide recommending that // be used for all comments (including multi-line comments), but I can't seem to find the reference right now. The Linux document doesn't give the rationale; however, I usually end up doing this so that when the leading /* character rolls off the screen in a long comment section, it is still clear that I'm looking at a comment block. (Perhaps this is what @johnmyleswhite was getting at.)

The point here is that C provides multi-line comments, yet many C programmers don't really use them in that way.

Based on this, I'm inclined to infer the following about future Julia programmers: If Julia provides multi-line comment support (the equivalent of /* */), a non-trivial subset of Julia users are simply not going to use it. Which means that when it comes time to compose a project using multiple packages, we'll have a mix of multi-line comments formats. That is, we'll see

/*
 * stuff like
 * this
 */

and

/*
stuff like
this
*/

As a side note, one nice thing about /* */ comments is the ability to inline comments; e.g.

int foo(x, /* doc meaning of x */
          y, /* doc meaning of y */
          z, /* doc meaning of z */);

Of course, in this example, /* */ are not being used as "multi-line" comments, but something different ("inline comments"?).

[rahuldave]

Coffeescript has the nice

#

bla

#

http://coffeescript.org/#strings

On Thu, Sep 5, 2013 at 8:37 PM, Benjamin Silbaugh
[email protected]:

The Linux kernel coding style document (
https://www.kernel.org/doc/Documentation/CodingStyle) states that the
preferred style for long (multi-line) comments is:

/*

• This is the preferred style for multi-line
• comments in the Linux kernel source code.
• Please use it consistently.
  *
• Description: A column of asterisks on the left side,
• with beginning and ending almost-blank lines.
  */

I've also seen this in many other C and C++ projects. I seem to recall
reading a C++ style guide recommending that // be used for all comments
(including multi-line comments), but I can't seem to find the reference
right now. The Linux document doesn't give the rationale; however, I
usually end up doing this so that when the leading /* character rolls off
the screen in a long comment section, it is still clear that I'm looking at
a comment block. (Perhaps this is what @johnmyleswhitehttps://github.com/johnmyleswhitewas getting at.)

The point here is that C provides multi-line comments, yet many C
programmers don't really use them in that way.

Based on this, I'm inclined to infer the following about future Julia
programmers: If Julia provides multi-line comment support (the equivalent
of /* */), a non-trivial subset of Julia users are simply not going to use
it. Which means that when it comes time to compose a project using multiple
packages, we'll have a mix of multi-line comments formats. That is, we'll
see

/*

• stuff like
• this
  */

and

/*
stuff like
this
*/

As a side note, one nice thing about /* */ comments is the ability to
inline comments; e.g.

int foo(x, /* doc meaning of x _/
y, /_ doc meaning of y _/
z, /_ doc meaning of z */);

Of course, in this example, /* */ are not being used as "multi-line"
comments, but something different ("inline comments"?).

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

Dr. Rahul Dave
ADS, Center for Astrophysics
Harvard University
[email protected]
(રાહુલ દવે)

[StefanKarpinski]

And we've come full circle. I'm considering closing the issue now and pretending it was just an epic troll all along.

[JeffreySarnoff]

+1 for #= =#, as it is the selection preferred by the selectors and it would be better decided before closing

[kkylin]

Hi,

I'm new to Julia, so this question may be a bit late. But maybe it's still relevant. Would you consider adding a mechanism for commenting an entire block, e.g., something analogous to Scheme's "#;"? That is, an operator -- let's call it "@#" -- such that

@# begin
...
end

would comment out the entire block (and similarly for other types of block structures). I frequently find this useful in debugging.

@# is just the first idea that came up, as it seems the behavior of this thing is macro-like. Indeed, one can easily write a macro that replaces a given block with something innocuous, though this won't be quite right semantically if the block in question comes at the end of, say, a function definition. Also, some form of this may be useful inside mathematical expressions, though naturally there is some ambiguities that would have to be resolved, and this would be hard to do with a macro.

If this has been discussed elsewhere already, or in fact discussed & rejected, please let me know. Sorry to prolong this long-running discussion. :-)

Cheers,
KL

[sharmi]

+1 for multiline comments. Any choice is fine!

[stevengj]

Note that people having difficulty with multiline comments came up twice on the mailing list in the last few days. What's worse is that some people are starting to define macros or use quote to emulate this, which seems like a monstrosity that we should head off.

Clearly, editors aren't good enough yet. Or users aren't good enough at choosing/using their editor, which is a more difficult problem to solve.

The consensus seems to be #? ... ?# for some choice of ?. Both | or = seem reasonable for ?. My preference would be for ? to be a form of bracket, e.g. #{ ... }# (a nod to Pascal), to take advantage of editor brace matching.

[stevengj]

(Attractiveness of multline comments is not a big concern to me. In fact, I would call unattractive multiline comments a feature, not a bug: this is something that should be used for quick debugging hacks, whereas for permanent documentation I would still prefer to encourage a # prefix on each line to visually distinguish comments from code.)

[thomasmcoffee]

A lot of the ambiguity issues discussed above have to do with distinguishing between a proposed multiline comment operator, for instance

#{ ...code commented out... }#

and a combination of one-line comments with valid code

#{ ...array at end of line, commented out... }# documentation comment.

It might be too late, but what if one-line comments were _required_ to leave a space (or more) after the # character? This certainly wouldn't be bad for readability :-)

I've actually been using a @# macro as suggested by @kkylin , and I've found it's nice to extend this to other kinds of "commenting" macros, too: for instance, I recently wrote a pair of macros for debugging, where one wraps a block of code, and inside it another effectively comments out its argument expression except when the wrapped block throws an error (particularly useful for debugging loops, though mine is not fully robust yet).

The only significant limitation of the macro approach is commenting out arbitrary forms within expressions, which suggests read macros.

Clojure uses just such a system as standard:

• one-line / rest-of-line comments with a single character (;)
• whole-expression comments with a macro (comment, which evaluates to nil)
• arbitrary-form comments with a read macro (#_, which effectively disappears, often used with "..." enclosing the commented code)

This system together seems to provide easy support for all the use cases described in this thread (including inline comments), with extensibility for power users.

Issue https://github.com/JuliaLang/julia/issues/455#issuecomment-4178835 raised the specter of syntax highlighting trouble against read macros, but at least one Clojure editor appears to support syntax highlighting for the #_ read macro [1]. I have not used it, but maybe this is a special case?

[1] http://code.google.com/p/counterclockwise/issues/detail?id=109#c2

[simonster]

Julia doesn't have read macros, but you can comment out arbitrary text with a non-standard string literal:

macro comment_mstr(x) end

comment"""
Not parsed or interpolated.
"""

I'm not entirely convinced this needs to be in Base, though.

Another not entirely serious option: → and ←.

[StefanKarpinski]

The most important use case, IMO, is not multiline comments but _inline_ comments. Using quotes and macros don't really work very well for this case. I still support #= ... =# but someone has to implement it.

[thomasmcoffee]

you can comment out arbitrary text with a non-standard string literal

The difference is that an empty macro evaluates to nothing, so it doesn't satisfy many of the use cases, for instance:

(x, comment"y," z) => error

foo() = option(1) comment"option(2)" => error

begin
foo()
comment"optional()"
end

=> nothing

The same is true of the comment macro in Clojure, which is the reason for the read macro.

[patrickeganfoley]

I like @#, but it might be more typing than people like.

My one cent is that

#

multiline
comment

#

Would be bad for me, and possibly other people. I thoughtlessly use #, ##, ###, or any number of #s when I'm commenting things out, based on how nice it looks. ## is pretty popular. I think it might cause strange behaviors if this kind of thing is common.

[tknopp]

Just wanted to express that I also like #= ... =# a lot and for commenting out larger code blocks this would be really handy. Unfortunatly my lisp foo is non-existent so that I can't help with the implementation.

[stevengj]

As mentioned in #6132 and #6444, the #= .... =# syntax is proving somewhat annoying in practice because # can start either a single-line comment or a multi-line comment.

How about %= ... =% instead? There is some precedent for % as a comment character (Matlab), % is never used before or after an = in current valid Julia code, and statistics in #6128 suggest that % is rarely used in Julia code anyway.

[JeffBezanson]

Technically %= is an operator.
It makes sense to me to use # since it is already associated with comments.

[johnmyleswhite]

What about using the likely-to-be removed #=#? It make multiline comments more burdensome to use, but it would substantially lower the probability that you create a multiline comment by accident.

[StefanKarpinski]

Multiline comments generally come in pairs and there's no mate for #=#.

[johnmyleswhite]

I guess nobody would ever concede to the use of #=#= as the comment start.

The current multiline comment start sequence broke a lot of code I'd written that looked like:

#=============
# Comment
#=============

Since I've employed a bunch of other similar comment blocks with #--- or ####, I hope we don't clobber those in the future.

[stevengj]

Okay, nix on %= .. =% then. I'm running out of sane ideas.

[thomasmcoffee]

@johnmyleswhite do you think #___ and ___# would also clobber common formatting patterns?

It certainly seems rare that triple-underscores would occur as variable name prefixes (does not occur in base, as both single- and double-underscores do).

[stevengj]

It's relatively hard to visually count underscores in order to distinguish #__ from #___, at least in my font. The other possibility mentioned in #6128 was #% ... %#, which is kind of ugly and no one really likes it but seems relatively unlikely to collide with single-line comments (probably precisely because it is ugly, combined with the fact that % is rarely used).

Or we can just stick with Stefan's original #= ... =#. It just seemed worth revisiting now that people have had a chance to try it, before it is set in stone (well, in clay at least) by the 0.3 release.

[staticfloat]

I think sticking with #= is a good idea, and users will just have to not have code such as @johnmyleswhite's above. We just have to avoid a syntax that could cause naive commenting to create a block comment, (e.g. #{ could arise from having an Any dict being defined at the beginning of the line) and #= seems to do that for me pretty well.

[thomasmcoffee]

It's really hard to count underscores in order to distinguish #__ from #___.

Doesn't seem so hard if you're the one typing it (you can feel and watch them appear), and no reader would practically need to distinguish the two.

If you give up on visually obvious directionality, I see no good reason not to be Lisp-y and go with #| and |# --- the start-frequency statistics for | vs. % in base (https://github.com/JuliaLang/julia/pull/6128#issuecomment-37433857) are different mainly just because the definitions for % are written using rem.

[nalimilan]

It may be OK to go with #= as long as a warning is printed when #== is encountered. It would be too bad that for such a small feature as multiline comments some people get trapped into weird errors when drawing ASCII art headers like in https://github.com/JuliaLang/julia/issues/69#issuecomment-39747985.

[ivarne]

The header problem can also be solved by requiring whitespace surrounding the #= =# identifiers.

[staticfloat]

+1

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

[LeoK987]

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 [e-mail]
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
https://github.com/JuliaLang/julia/issues/69#issuecomment-285697167, 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 #-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

=]