Interpolate and indent block comments?

[StanAngeloff]

I was just browsing through 0.9's online reference and spotted this example:

###
CoffeeScript Compiler v0.9.0
Released under the MIT License
###

How about interpolating variables and expressions inside block comments? This would make them much more useful:

###
CoffeeScript Compiler v#VERSION
Released under the MIT License
###

One fact I don't like about the output is comments are not indented like regular JavaDoc strings:

/*
CoffeeScript Compiler v0.9.0
Released under the MIT License
*/

It's much more appealing to indent each line so contents appear to be inside the comment:

/*
 * CoffeeScript Compiler v0.9.0
 * Released under the MIT License
 */

It is also easier to spot without a syntax highlighter.

[TrevorBurnham]

Hmm, the first suggestion is really cool, but it would also be really annoying to unintentionally have something of the form #foo in a block comment, run the code and get a console error foo is undefined. On the other hand, block comments should really only be used in CoffeeScript when you have a clear intent, so maybe this would be rare. In any case, I think such mistakes would be way less likely if we only allowed string interpolations of the form #{...}, as in Ruby. (This is also nice because then your text editor knows to add the curly braces for you when you use # within a string.)

+1 to the second one. It's slightly less byte-efficient, but it's the standard and people expect it.

[michaelficarra]

Actually, after hearing TrevorBurnham's argument, I think I may have to change my opinion about the automatic interpolation. If I comment out a string with interpolation in it as well as the definition of the variable being interpolated, it will cause a reference error. This might be pretty unexpected behaviour, and the convenience may not be worth the trouble it causes. Even interpolations of the form #{...} would be affected by this. Still definitely +1 to the second suggestion, though.

[TrevorBurnham]

By the way, there's discussion of requiring #{...} for interpolation instead of allowing #var over at issue 581.

Re michaelficarra: Maybe the right approach (though it may be a parsing nightmare) is to allow interpolation within block comments except within double quotes, where such interpolations would be valid without the commenting? But I really don't think it's much of an issue. Block comments are supposed to be for things like documentation, not for commenting out code (no reason to preserve commented-out code in the JS output, right?).

[hen-x]

JavaDoc-style asterisk prefixing in block comments is a great idea. As for interpolations, how do we determine the value of a variable at compile-time? Currently there is no notion of a permanent constant in the language, so this would presumably entail actually executing code during its own compilation, which is a minefield of potential side-effects and weird errors.

[StanAngeloff]

@sethaurus: The variables will come from the compiler itself or any files required with the still missing -r options. So I imagine you would do something like:

coffee -c -r constants.coffee input.coffee

This would require('constants') before compiling the input. In an interpolation, we recursively call the .compile method on the CoffeeScript object to get the evaluated result.

Perhaps interpolations should use another form so it's clear they won't be from scope, i.e., don't expect them to work with variables defined earlier in the script. Back to $var?

[hen-x]

@StanAngeloff thanks for the clarification!

[StanAngeloff]

If a commit I requested a pull on gets merged in (tiny one so fingers crossed), the first part of this issue can be ignored. I gather from the replies everyone's in favour of the second bit about producing nicer looking comments and that should be easy enough to resolve.

[jashkenas]

Interpolation in comments isn't going to happen -- that's a pretty strange idea, given that comments "happen" at compile time, not execution time, and should never have anything to do with the surrounding code. Imagine having a syntax error in your comment, and your comment failing to compile...

As to the JavaDoc-style comments, that's definitely what we would do if we were compiling to Java -- but we're compiling to JavaScript here, where the style has no special intrinsic significance. Is this just an aesthetic thing, or is there a practical reason to prefer JavaDoc-style comments in JS over simple-style ones?

[jashkenas]

I've looked through some of the top JS repos, and the two-thirds majority prefer // style comments to /* ... */ style comments. I do as well.

We talked about it a bit in #coffeescript, and the argument for JavaDoc-style comments with asterisks running all down the left-hand side seems to rest on the idea that if you're in an editor with no syntax highlighting, and are using a block comment to comment-out a large chunk of code, you need to be able to tell that the code is commented-out. // comments have no such problem, and are cleaner to read as well. Here's the patch that makes CoffeeScript block comments generate // JS comments:

http://github.com/jashkenas/coffee-script/commit/143c4d5efcab338b7bfcea127b4acc08de5dfb32

Closing the ticket...

[TrevorBurnham]

I strongly recommend reverting to /* ... */-style comments for block comments in CoffeeScript. The main purpose of CoffeeScript block comments is for licenses, etc., which need to be preserved in minified output. While minifiers vary, it's generally much easier to preserve block comments than line comments, because line comments are assumed to be superfluous. To give some specific examples:

1. Sprockets strips out all line comments and preserves block comments.
2. YUI Compressor preserves only block comments starting with !.
3. Google Closure Compiler preserves only block comments starting with * @preserve.

I think it's very desirable for CoffeeScript to support all of these syntaxes. (You could use backtick escapes, of course, but this is bad aesthetics.) Longer-term, if the parsing can be figured out, it would be ideal to preserve line comments in JS output as well, and to give them the // syntax.

[StanAngeloff]

Thanks jashkenas. I like this approach better and it makes things look much much better in the output.

[jashkenas]

Trevor: then what do we emit? /* ... */, /*! ... */, or /* @preserve ... */ ?

The fact that different toolsets treat them differently doesn't seem to be a compelling argument for picking one over the others. Really, what this demonstrates is that it's better to have your build task prepend your license to your minified file, and not bother with learning special minifier directives, no?

Feel free to pop into #coffeescript if you want to discuss it.

[TrevorBurnham]

I was only suggesting that we emit /* ... */ (with no added spaces), and then all of the syntaxes I described can be supported (the Sprockets one with no extra work, the YUI Compressor one with ###! ... ###, and the Google Closure Compiler one with ###* @preserve ... ###).

Requiring people to keep their licenses in separate files is an inconvenience. In my mind, it defeats the main purpose of block comments.

[TrevorBurnham]

We've been discussing this for a while in IRC now. There are several related issues at work here. I wanted ###...### should compile to /*...*/, including allowing ###!...### to compile to /*!.../* (for YUI Compressor), for example; that's the closest thing to a standard for preserved comments that there is (see http://code.jquery.com/jquery-1.4.2.min.js, for example). However, currently ### only acts as a block comment delimiter if it's on a line by itself. One reason for this is that, in Docco, Markdown is allowed; so ### Foo within a block comment is an <h3> header. Also, ### Comment ### causes a parse error right now.

My proposal is that ### should always be able to start a block comment, no matter where in a line it is, but only ### at the end of a line (excluding whitespace) should count as the end of one. Also, JavaDoc-style comments should be used (part of the reason for the switch to //-style comments was that it lets you clearly know when the output you're looking at is a comment). So:

### Comment ###

should compile to

/* Comment */

and

###!

### Foo

###

should compile to

/*!
 *
 * ### Foo
 *
 */



### One

code code code ....

### Two

comment comment comment ...

###

should compile to

/* One
 *
 * code code code ....
 *
 * ### Two
 *
 * comment comment comment ...
 *
 */

I think of the main purpose of block comments as being to include licenses in output, and this approach allows CoffeeScript to be consistent with the most common style. What does everyone think?

Update: To take an example from Jeremy,

### One

code code code ....

### Two

comment comment comment ...

###

should compile to

/* One
 *
 * code code code ....
 *
 * ### Two
 *
 * comment comment comment ...
 *
 */

[TrevorBurnham]

Relatedly, this currently causes a parse error:

###
end of file

I think there should be an implicit ### at the end of the file in this case, so that the compiled output is

/*
 * end of file
 */

This is consistent with the way that the TextMate bundle does syntax highlighting, and with the way that an open /* works in JavaScript (at least as far as I can tell). Not a big deal, it just feels like a parse error is a bit harsh.

[jashkenas]

Alright, Trevor, there's a patch now on master with an alteration to the herecomment lexing regex that I think will serve.

Here's a bit of Coffee:

insideSomeFunction ->

  ###
  A
    B
  C
  ###

  one code

  ### @preserve This is a comment ###

  two code

  ###*!
   * one
   * two
   * three
   ###

  three code

And here's the compiled JavaScript that master now generates:

insideSomeFunction(function() {
  /*
  A
    B
  C
  */
  one(code);
  /* @preserve This is a comment */
  two(code);
  /**!
   * one
   * two
   * three
   */
  return three(code);
});

Suit your fancy?

[unity]

Coming from #379 (comment), where I was searching for a solution for Markdown formatted JSDoc comments, and the impossibility to write ### inside of those.

I couldn't find one from reading this thead.

One could expect one of those to work, but none do :

  ###*
    ### Markdown title level 3 
  ###

  ###*
  * ### Markdown title level 3 
  ###

  ###*
  # ### Markdown title level 3
  ###

A clarification for this use case would be nice.

[satyr]

See #1050 also. IMO, that's unfixable as long as we stick to triple-hash.

Ironically, CoffeeScript itself suffers from this mischosen syntax wrt Docco: ### H2 doesn't work.