Block and Partial Line Commenting

[ghost]

It would be great if CoffeeScript could have block and partial line commenting similar to JS's /* ... */.

Here are two useful use cases:

1. Embedding comments in the middle of a line -- for example, to use a technique outlined in David Flanagan's "JavaScript: The Definitive Guide" book:

func: (one, two, three, /* optional */ four, /* optional */ five) ->

2. Commenting out blocks of code for debugging purposes.

jashkenas pointed out on IRC that you can already do that by selecting all the lines and commenting out all of them using a proper shortcut key, if the editor supports it.

But that's the thing: if the editor supports it. If you're using a bare-bones UNIX editor installed by default on a remote machine, you possibly don't have such a line-commenting command available for CoffeeScript.

What do you think?

Am I the only one liking David Flanagan's technique to mark optional arguments? Do you find it useful? Would you consider using it?

And the ease of commenting out lots of lines by just typing, in JS's case, /* and */ before and after those lines in a simple editor? Do you care about this, e.g., when remotely accessing UNIX machines?

jashkenas told me to bring this up for discussion... so, here it is. :)

Please post here on whether you consider block and partial line commenting useful or not.

[andreyvit]

I'm not missing any of it, but partial line commenting seems useful, exactly for the purpose you mention.

Personally, for optional comments/varargs I often add a "real" signature on the previous line, like:
# func(a, b, [c, d])
func: (a, b, c, d) -> ...

Block commenting with /* */ is very hard-to-type, nearly every editor can handle insertion of '#'. Most remote Unix machines come with Vim, which will happily insert #s. (Not sure if does so out of the box, but there's surely a :noremap one-liner for your .vimrc for that.)

[StanAngeloff]

I find /* ... */ extremely useful when combined with //:

//* DEBUG:
remove_the_leading_slash_to_disable_debug_code();
one_keystroke_away_yatoo()
//*/

[ghost]

StanAngeloff: Wow. That's a useful technique!

If both // and /* .. */ get in, I expect to be using that trick quite often for code that I keep improving and debugging from time to time.

Interesting how I've never thought of that one before. Very cool.

[ghost]

andreyvit: On US-like layouts // is actually easier to type than #, which requires pressing Shift+3. At least on standard Mac / Windows programming editors as well as Emacs. Don't remember about Vi-like editors, though, maybe you have a point there. Or do you have another keyboard layout?

But anyway, I like # comments as well as //. Both have visual vs. typing advantages. I don't see them as mutually exclusive.

[weepy]

is harder to type, and is divergent from JS. I can't think of any upsides. It's also a shame to lose /* */

// && /* */ >> # FTW!

[ghost]

weepy: Yes, if I have to choose between them, I choose // and /* */, too.

[andreyvit]

I think the upside is that # is a standard comment style in most kinds of Unix scripting. As such, it is supported out of the box by, say, TextMate (and probably Vim).

As for being hard to type, Command-/ types it (without requiring me to move the cursor to the start of line).

[ghost]

As such, it is supported out of the box by, say, TextMate (...)
As for being hard to type, Command-/ types it (...)

andreyvit: Command-/ in TextMate will use the line-commenting syntax defined in the current language's bundle. Try it with a .js file – TextMate will insert "// ". Emacs works in a similar manner. And this is great, because commenting syntaxes do differ between languages.

So, as long as the CoffeeScript TextMate bundle gets updated to use "// ", Command-/ will insert it. The corresponding commands/keys will act accordingly when Emacs' CoffeeScript mode is updated.

That said, I'm glad you mentioned the shortcut key issue, because it highlights the importance of having only one kind of line-commenting syntax. But this, of course, doesn't exclude a block/partial-line commenting syntax.

[StanAngeloff]

The strongest argument against multi-line comments seems to be readability (was it you Jeremy?) Are we seriously dumping them just because Mac IDEs have built-in support for Command+/ and single-line comments supposedly look better?

[holmsand]

I find "#"-style comments easier to read than multiline "/* comments */" (despite being used to Javascript and Java). IMHO readability is more important than anything else.

Besides, you don't need a fancy editor or IDE to comment out a block with "#". See for example http://notfaq.wordpress.com/2006/07/28/vim-comment-blocks-of-code/

[ghost]

holmsand:
The thing is: they are not mutually exclusive. They can both co-exist, as they do in JavaScript and other languages.

Line-comments are better in some cases, and block/partial-line comments are better in other cases. Thus my suggestion of adding block/partial-line comments, not eliminating line-comments.

[holmsand]

brightnow:
I agree that multiline comments have their uses, but I just don't think that they are useful enough to merit being in the language. Coffeescript is a very simple language, and that is what I like about it.

If multiline comments are in the language, they will be used, and people will have to read them. Including stuff like StanAngeloff's debug hack above, which pretty much forces you to use a syntax-highlighting editor to make sense of the code.

[StanAngeloff]

@holmsand: not being picky here, but you don't need a fancy editor or IDE to have syntax-highlighting. Vim does it, every other editor where you can force JavaScript highlighting can do it too.

@brightnow: I am doing a branch with multi-line comments for my own use. I will update you on private if I get a chance to finish it tonight.

[holmsand]

StanAngeloff:
Absolutely being picky here, but vim with coffee-script-plugin is kinda fancy :-)

[ghost]

holmsand, regarding simplicity, IMO, block-comments don't make a language complex. But, well, the question here is, where do we draw the line?

I think that the advantages of having block/partial-line comments in CoffeeScript outweigh the disadvantages.

Quick summary of advantages (some we haven't spoke of before):

• Easier conversion of existing code from JS to CS

• Commenting out code in the middle of a line, for debugging purposes, e.g.:

  puts one + /* + */ three + four

• David Flanagan's optional technique and other kinds of code marks:

  func: (one, two, three, /* optional / four, / optional */ five) ->

• Ease of typing /* and */ before and after nn lines and you've commented them out (particularly useful when debugging)

• StanAngeloff's debug technique (eventually slightly altered for the "#" line-comments, if these stay in)

@StanAngeloff: "a branch with multi-line comments", cool! Let's hope it will get into the official repo as well.

[andreyvit]

Calling Vim non-fancy was unexpected for me too. :)

Regarding # or Command-/, I only wanted to say that # (as opposed to //) is more or less a Unix scripting convention, so all other things being equal, it will lead to better “out-of-the-box” experience with text editors.

I don't buy “/* ... */ needs syntax highlighting” argument. Huh? Do you seriously work without syntax highlighting?

I also don't buy the simplicity argument, but I guess I may be unqualified to judge here (maybe — maybe — someone, somewhere on this planet really has a problem learning another comment style, dunno).

My opinion is that we can have /* .. */. It does not hurt those who don't want it, and it helps those who want it, so why not?

[ghost]

andreyvit: Markdown ate your asterisks, in the last paragraph. ;)

[StanAngeloff]

Here is the grand total for those interested. You can merge it in your own fork.

[ghost]

StanAngeloff: Looks good. Thank you!

...But I'd like to know if it is accepted into the official repo, before I use it extensively.

[jashkenas]

Block comments are now on master, in the form of "herecomments". They work identically to the way our current heredoc strings work, and follow the same indentation rules. A ready-to-hand example:

###
The CoffeeScript Lexer. Uses a series of regexes to attempt
matches against the beginning of the source code...

    [tag, value, line_number]

Which is a format that can be fed directly into Jison.
###

Produces this JS:

/*
The CoffeeScript Lexer. Uses a series of regexes to attempt
matches against the beginning of the source code...

    [tag, value, line_number]

Which is a format that can be fed directly into Jison.
*/

There's already support for highlighting these on the TextMate bundle, and it would be great if other highlighters could pick it up as well.

Closing the ticket.

[StanAngeloff]

Jeremy, would you consider having an alternative syntax for Javadoc following the same style of heredoc strings:

###
I am just a regular multi-
line comment
###

######
This function does XYZ.

@param  {String}  ...
@return   String  ...
######
fn: (string) -> string

should compile to:

var fn;
/*
I am just a regular multi-
line comment
*/
/**
 * This function does XYZ.
 * 
 * @param  {String}  ...
 * @return   String  ...
 */
fn = function(string) {
  return string;
};

Happy to provide a patch.

[GeoffreyBooth]

This is fixed via #4572. Sorry it took awhile.