New comment syntax.

[dom96]

Let's implement a new comment syntax for 0.10.0. Current syntax discard """ ... """ is too ugly and too much hassle to write. It's about time I make this feature request official and create an issue for it. So here it is.

@Araq's suggestion on IRC was #[ ... ]#.

Other possible contenders: ### ... ###, {- ... -}, (* ... *).

Suggestions and discussion encouraged.

Also, let's be democratic: so in your reply tell us if you think this is a good idea or not with a unambiguous Yes or No.

Forum discussion here.

[fnordbg]

Yes for the pound and square bracket. Looks like it has the best tradeoff for cleanliness and noticeability.

[refi64]

No for {- ... -} (ugly and ambiguous; at first glance, is it a comment or mapping?) and (* ... *) (too OCaml-ish).

Yes for #[ ... ]# and ### ... ###. Mostly yes for #[ ... ]#, since it doesn't cause confusion with doc comments (## ...).

[rbehrends]

I personally don't see the need for a multi-line comment syntax. "when false" and "discard" are perfectly fine for temporarily commenting out multiple lines of code, not to mention that any editor more modern than edlin should make it easy to use "#" to comment out a block of code. If you insist, then an empty pseudo-procedure should also do the trick:

comment """
This is a comment.
"""

I'm mostly not sure what functionality multi-line comments would add; an actual use case would be nice to see. (I could see the case for commenting part of the line, e.g. to annotate individual procedure parameters, but that's a different use case.)

In my experience, these types of comments tend to also get turned into something like this, anyway:

/*
 * This is a C comment.
 * With a column of asterisks down the left side.
 */

At which point there's no real difference compared to using single line comments.

[gradha]

template c(comment: string) = discard comment

c"""
Nimrod
is
awesome
"""

[dom96]

@kirbyfan64 I should mention that with the #[ ... ]# scheme ##[ ... ]## would be a doc comment.

@gradha hrm, that looks tolerable actually. I wonder if we could get away with using an operator instead of the c? I'm glad you're still with us btw, your activity ground to halt recently.

[refi64]

@dom96 I was guessing that. It's just that the ## ... ## gets a tad confusing:

• `# ... Regular comment
• ## ... Doc comment
• ### ... ### Multi-line comment
• #### ... #### Multi-line doc comment?

Using discard """...""" gets annoying after the 20th comment.

[dom96]

@kirbyfan64 Yeah, I agree. I'm starting to like #[ ... ]#.

[jovial]

I agree with rbehrends; not sure about the pseudo procedure though. I like the mantra that there should only be one way to do things.

[achesak]

I'd definitely like a multi-line comment syntax. Not a fan of the {- -} and (* *) ideas though, and I agree with kirbyfan64 about how confusing the ### ### style could get.

[ ]# looks the best to me.

[rbehrends]

I have to say that I am wondering what it is that other people use multi-line comments for? I mean, if I want to comment multiple lines, I mark a block, hit Command-/, and comments are added to each line in that block. I do it again and they are removed. If anything, multi-line comments make this kind of operation harder to automate.

[dom96]

I suppose it is true that as long as your text editor/IDE supports that then there is no issue.

[Varriount]

@rbehrends @dom96 Why not have the new multi-line comments become doc-comments? Currently, typing doc-comments requires adding a ## to each line.

[dom96]

@rbehrends @Varriount That reminds me: you would need two separate key bindings one to add # to each line that is selected and another for ##. It may be easy in Vim or Emacs but not in other editors.

[rbehrends]

@dom96 That's a different issue. If you really only insert a multi-line comment marker at the beginning and end, it'd save you some typing for new comments. But in reality, you still want a visual hint on each line: for example, try to make sense out of a git diff or git blame output where you can't easily tell if code is part of a comment or not. Heck, even Vim's syntax highlighting often goes out of sync with long comments or #if 0 ... #endif. This is part of why even though C does have multi-line comments, people still often write them as I've indicated above.

[h42]

For actual comments, I usually use single line comments on every line. However, when I port code from another language or another program, I like to copy the foreign code into the area I am working on. A multiline comment comes in handy there. Single line comments get in the way even if you use a powerfull editor. I like the #[ ]# syntax or /* */ as it is so prevalent and there is already a close coupling to c.

[fowlmouth]

Lua uses -- for single line and --[[ to --]] for multiline, this has the advantage that you can leave a --]] at the end of a section of code and not have to bother with it when you uncomment it. You can add another -- to the first one to make it a normal line comment.

I suggest #[ and #] for nim

[onionhammer]

Why not #..... # for consistency.

[FlatMapIO]

..... # +1

[bogen]

I like #[ ... #] or #[ ... ]#. I think #[ ... ]# looks better, but I see the practicality in #[ ... #]. Either is fine with me, but my vote is for #[ ... ]#.

[barcharcraz]

I really don't see the point in a block comment syntax, not once have I been like "boy I wish nim had block comments". I see the point for porting code, but discard """ """ works really well there.

For the cases where discard """ """ is not a good solution I think that editors that just add a # if you press the return key on a line that has a # should do fine, and that is all editors ever. Also I don't understand how #* and *# is more consistent than anything else, or is it just that code that looks like C must be fast and good?

Understand that C started with ONLY /* and / (and indeed it still has only those if you are using C89 as god intended) and only later did it get //, because people found / and / annoying even with editors. I have never found // annoying with editors and only really use / and */ because Microsoft's C computer does not support //.

[refi64]

@barcharcraz Your comment formatting got goofed up. Escape your asterisks.

[reactormonk]

How about no block comments and repeat the single line comment escape? Does the AST look different in each case? I'm influenced by ruby, where there are no multiline comments and I don't see what multiline comments provide over just repeating the single-line comment escape.

[dustinlacewell]

I don't know why we're discussing this after the comment macro was suggested.

[ .. ]# if we have to use something ridiculous.

[dom96]

I think we need to decide what to do about this before the release of 1.0 so I will mark it as a Showstopper.

[Araq]

No, the compiler warns about `#[``already, so we can make that an error for 1.0 and then later have a multiline comment without breaking anything. So no showstopper.

[gmpreussner]

I know that this is an old discussion, but I took quick stab at creating a nim syntax highlighting file for Kate, and it looks like there is no convenient way to look ahead more than two characters. While #[ .. ]# for multiline comments would be fine, something like ##[ .. ]## or ### ... ### could be problematic.

I also agree with @rbehrends that there is not really a need for multiline comments. However, when commenting out portions of code, the 'when false' approach - while syntactically sufficient - may not provide enough visual clues about the code inside being excluded from compilation. That would require evaluation of the 'when' expression, which is probably deseriable, but may also not be easy to integrate in some text editors.

[Varriount]

I don't know about highlighting the entire block of code inside the 'when false' block, but highlighting 'when false' itself can be done quite easily in sublime text.

[gmpreussner]

Yeah, but if 'when false' is being highlighted then other expressions that evaluate to false should probably be highlighted as well (for consistency). I think that greying out inactive code would be a desirable feature in any text editor.

By the way, I was wrong about the two character look ahead in Kate. Besides regular expressions there is also a way to look ahead by string matching, so no problem there. That doesn't mean those long comment patterns would be a good idea though. If it looks or feels awkward, then it probably is :)

[ReneSac]

I don't see the need of yet another syntax for comments, as both discard """ """ and editor support for # seems sufficient for me (the last one has the advantage of being nestable). If I were to chose one of the suggested syntaxes, I prefer the #[ ... #] suggested by fowlmouth.

Is there a non-aesthetical reason for #[ ... ]# be preferred over the foulmouth suggestion? Not that aesthetical reasons aren't important (they seem to be the main reason for this RFC after all).

@gmpreussner: kate highlights #if 0 for C, as that is basically another way to comment code. It is kinda equivalent to Nim's when false. But w/o compiler support it is difficult to know if a more complex expression also evaluates to false.

[ghost]

No

[Deco]

I think Nim should definitely have a multiple comment levels; Lua does and I find it to really good for productivity. In C, you can't nest multiline comments /* /* */ */. In Lua, you can't nest but you can introduce a new comment level like so --[===[ outer --[[ inner ]] outer --]===]. The parser doesn't see --[[ inner ]] as a nested comment, it just treats it as a comment. Because the outer comment started with three = symbols, it won't end the comment until it sees --]===]. How about this for Nim:

code
broken code 1
#[
commented code A
#]
broken code 2

In C/C++, you'd need to individual comment the broken code sections, or remove the multiline comment terminator of commented code A. Proposed solution:

code
#[[
commented broken code 1
#[
commented code A
#]
commented broken code 2
#]]

I suggest the terminator be #] rather than ]#, otherwise it may be written accidentally:

a[0] = b[0]
#[
a[1] = b[1]# this is a comment, note that it accidentally terminates the multiline comment!
a[2] = b[2]
]#
a[3] = b[3]

Also +1 for ##[ ... ##] being a doc-comment!

[keyle]

Why does a language need multi-line comments? :-1:

# this is
# quite clean
# and IDEs
# won't mess it up as
# you can't double comment strings.

if ## indicates a documentation comment

### should
start a multiple line 
comment? ###

although clever, ### could get out of hand.

[crashoverdrive]

Single line comments makes for better code documentation. The present syntax is alright.

[Varriount]

Since there seems to be an abundance of opinions on this subject, I propose that anyone who really wants another comment type write up something akin to Python's PEP's, rather than simply stating opinion.

[oderwat]

I mainly need inline comments. Don't care about multiline to much but #[ ]# serves both. Done.

[ghost]

@keyle Araq has said that modern tools should be embraced, which I agree with, and programmers really ought to rely on capable editors. I'm not sure where the line is drawn though, but batch commenting doesn't exactly rely on complex technology.

Chances are there's something I'm not taking into account, but I'm sure there are people who want it specifically for the sake of convenience, and it would be good to know exactly what kind of tools we expect users to have.

I see that Aporia supports batch commenting, which is nice.

However, it doesn't really seem like a complex thing to implement, and if it doesn't imply some kind of tradeoff then there's no need to consider all these things.

[bluenote10]

Yes for #[ ... ]#. The big advantage over """ or ###: Even without syntax highlighting one can easily distinguish between the start and the end of a comment. In contrast to:

""" """
""""""
""" ""
"" """"""
"""

I do like multiline comments in cases where I want complete text editor freedom for documentation purposes. Some advantages of multiline comments:

• Much easier modification of text wrapping. Image you want to change the comments text wrap width from 120 characters to 80. Typically the repeated line prefixes # of single line comments makes both manual and automatic text wrapping more difficult to edit.
• Easier copy/past within doc strings. Imaging copy/pasting multiline console output in a should output: example into doc string.
• For some IDEs/editors the features for automatic inserting/extension of single-line comments often do not exactly what I want. To be fair: If I write a single comment, it is impossible for an editor to guess if I want to continue writing a comment in the next line.

[oprypin]

I 100% agree with @Deco's comment which shows that #[ ]# is completely non-viable. I vote for #[ #], nestable like shown by @Deco. I like #{ more, though.

[yglukhov]

I've suddenly seen some scala example that brought me to the following "why nots":

#!/bin/sh
echo This is a shell script.
echo Also this happens to be a multiline comment :-P
# Why not install nim if it's not installed here %)
!#
echo "This is a nim program"
#! another comment here. #! Also why not nest them !# !#

[refi64]

@yglukhov Scala is an excellent example of what not to do. :)

Really, though, I think this needs to be in Nim before 1.0. discard """"" gets annoying quickly, especially when what you're trying to comment out triple quotes.

[rbehrends]

@kirbyfan64 What I'm still not seeing for this particular use case is why this isn't something that an editor cannot do for you. I hit Command-/ in TextMate or ,c in Vim, and I'm done. Incidentally, if you're using Vim and need it for that, here are some convenient bindings:

map ,c :Comment<CR>
map ,u :Uncomment<CR>

com! -range Comment <line1>,<line2>s/^/# /
com! -range Uncomment <line1>,<line2>s/^# //

The other use case where you may need comments with a begin and end are inline comments, e.g. something like this (borrowing Haskell syntax for inline comments):

proc foo(arg1: Type1 {-comment1-}, arg2: Type2 {-comment2-}) = ...

I'd argue that this is a much less important use case and can easily wait until after 1.0.

[refi64]

Yeah, IDEs can definitely do it. Which is great.

When you use an IDE.

[rbehrends]

@kirbyfan64 I do not use an IDE. Any editor more advanced than edlin should be able to do it.

[oderwat]

I still really just want some inline comments... block and line comments are simply not enough. And comments should nest. #[ ... #[ ... #] #[ ... #] ... #]...

[reactormonk]

@oderwat Give me a use case.

[oderwat]

proc doSomething(a: int, b: string, c: int) = ...doit...

doSomething(1543231#[1544291#]#[996584#],"bla"#["blub"#],3#[or any prime#])

let x=y*1.14#[was 1.16 till yesterday#]*123.4#[should be calculated#]+100
let z=doSomething#[or doOtherthing#](1,2,3)

#[ need to fix that proc
proc ohMy(y: float): float =
  y*1.14#[was 1.16 till yesterday#]*123.4#[should be calculated but how?#]+100
#]
proc ohMy(y: float): float = 1234.5 # just use that for now

I would also prefer #< thats an inline or multiline comment ># over others because I think this makes the comment text itself more readable because [](){} are much more distracting. And I think ># is not as easily broken by accident as ]# could be. In addition it is easier to type for us germans and not harder for english keyboards (imho). With #< comment #> as viable alternative as it makes parsing probably easier.

[Araq]

I think now that the lack of inline comments is against Nim's design philosophy. We support foo x, y, x.foo y etc and yet cannot have 2 ways to write comments? That's just weird. While I personally don't need more comment syntaxes, others request inline comments and so we should introduce these:

#[comment here]
#[[comment here]]
#[[[comment here]]]
#[[[[comment here]]]]

With the level of [] up to 4. This means that regex based syntax highlighters can still process them properly (it adds 4 new regexes to the highlighter) and yet is flexible enough to allow for nesting in practice as well as crazy stuff like

code here
#]]] # end marker here left for easy code section deactivations

[Araq]

Implemented multi-line comments.

[dom96]

For reference: the syntax for multi-line comments we settled on is #[ ... ]# not #[ ... ]. They also should be nestable :)

On Monday, 18 January 2016, Andreas Rumpf notifications@github.com wrote:

Closed #1535 https://github.com/nim-lang/Nim/issues/1535.

— Reply to this email directly or view it on GitHub https://github.com/nim-lang/Nim/issues/1535#event-518083493.