Clojure

Real multi-line comments

Details

  • Type: Enhancement Enhancement
  • Status: Closed Closed
  • Priority: Minor Minor
  • Resolution: Declined
  • Affects Version/s: None
  • Fix Version/s: None
  • Component/s: None
  • Labels:
    None
  • Patch:
    Code and Test

Description

The (comment) macro is not a viable substitute for real multi-line comments:

  • It evaluates to nil, so isn't really useful except at the top level
  • It requires proper paren/etc nesting inside itself
  • Contents must be valid tokens; for example TODO: is illegal inside a (comment)

Common Lisp has #|...|# for multi-line comments, and I think Clojure would benefit from having them too. I've implemented #| to behave in a way that is identical (so far as I am able to test) to CL's implementation, and added tests to the reader test to verify that they work.

Apologies for my formatting in the java files not quite matching up with the rest of the code: I didn't want to go through the pain of making it perfect unless this patch would actually be accepted; I can go back through if necessary.

Activity

Hide
Anthony Simpson added a comment -

I am totally for this. I agree that comment isn't a valid substitution. comment is useless for a lot of things.

Show
Anthony Simpson added a comment - I am totally for this. I agree that comment isn't a valid substitution. comment is useless for a lot of things.
Hide
Benjamin Teuber added a comment - - edited

Nice - but are you sure just doing nothing on an unexpected EOF is a good idea?
I guess it usually means I've forgotten the close tag somewhere, so I'd rather be informed about it by an exception. Omitting the |# on purpose just to save two characters seems dirty to me.

Show
Benjamin Teuber added a comment - - edited Nice - but are you sure just doing nothing on an unexpected EOF is a good idea? I guess it usually means I've forgotten the close tag somewhere, so I'd rather be informed about it by an exception. Omitting the |# on purpose just to save two characters seems dirty to me.
Hide
G. Ralph Kuntz, MD added a comment - - edited

What about #_(...)?

I know that the parens have to be balanced, but other than that, doesn't it do everything else?

Show
G. Ralph Kuntz, MD added a comment - - edited What about #_(...)? I know that the parens have to be balanced, but other than that, doesn't it do everything else?
Hide
Anthony Simpson added a comment -

No.

user=> #_(TODO: Hi there!)
java.lang.Exception: Invalid token: TODO:

And then, as you mentioned, we have the paren balance problem. The idea is to have something completely ignores what is inside of it.

Show
Anthony Simpson added a comment - No.
user=> #_(TODO: Hi there!)
java.lang.Exception: Invalid token: TODO:
And then, as you mentioned, we have the paren balance problem. The idea is to have something completely ignores what is inside of it.
Hide
Alan Malloy added a comment -

Good point, Benjamin. I just assumed most languages didn't need comments to close nicely, but having tried it out I can't find a single one that would let me get away with an unclosed multi-line comment.

Revised patch attached, and using git format-patch now that I know it exists.

Show
Alan Malloy added a comment - Good point, Benjamin. I just assumed most languages didn't need comments to close nicely, but having tried it out I can't find a single one that would let me get away with an unclosed multi-line comment. Revised patch attached, and using git format-patch now that I know it exists.
Hide
a_strange_guy added a comment - - edited

You can use #_ with string literals already:

#_"TODO: Hi there!"

The only problem we have is that we don't have raw strings. I don't think that we need another litrals for comments.

And I don't see any use for multiline comments. In Java etc. you use them to uncomment parts of your program (we have #_ (...) for that) or to document classes & methods (we have docstrings which are superior). If you need multiline comments to explain some part of your code, then you should do something about the code (or use #_ "..." if you are lazy).

Show
a_strange_guy added a comment - - edited You can use #_ with string literals already:
#_"TODO: Hi there!"
The only problem we have is that we don't have raw strings. I don't think that we need another litrals for comments. And I don't see any use for multiline comments. In Java etc. you use them to uncomment parts of your program (we have #_ (...) for that) or to document classes & methods (we have docstrings which are superior). If you need multiline comments to explain some part of your code, then you should do something about the code (or use #_ "..." if you are lazy).
Hide
Anthony Simpson added a comment - - edited

Except with #_"" you can't just paste something in there because it has to be escaped properly if it has strings and such embedded in it.

Sure, we can work around these limitations somewhat. We can pile hacks on hacks to get half-working multiline comments or just add this trivial patch and have real multiline comments like every other language in existence. Just sayin'.

Multi-line comments aren't for just explaining bad code. #_ isn't designed for this and thus is not a solution to this, and marking every line of a prewritten text with ; and/or removing or editing it later is just tedious.

Curiosity: wouldn't this be useful for literate programming tools?

Show
Anthony Simpson added a comment - - edited Except with #_"" you can't just paste something in there because it has to be escaped properly if it has strings and such embedded in it. Sure, we can work around these limitations somewhat. We can pile hacks on hacks to get half-working multiline comments or just add this trivial patch and have real multiline comments like every other language in existence. Just sayin'. Multi-line comments aren't for just explaining bad code. #_ isn't designed for this and thus is not a solution to this, and marking every line of a prewritten text with ; and/or removing or editing it later is just tedious. Curiosity: wouldn't this be useful for literate programming tools?
Hide
Stuart Halloway added a comment -

Rich: if you are interested in this assign to me and I will screen.

Show
Stuart Halloway added a comment - Rich: if you are interested in this assign to me and I will screen.
Hide
a_strange_guy added a comment -

Don't think that this is a pressing issue, because every editor that has support for Clojure (or even just Scheme/CL) has a comment-region feature.

I would support adding a reader macro for raw strings, because that is an issue (almost every ns docstring is escaped), and if we had those, then multiline comments would be subsumed by them:

#_
#[[ ;; lua-like proposal for raw strings

]]
Show
a_strange_guy added a comment - Don't think that this is a pressing issue, because every editor that has support for Clojure (or even just Scheme/CL) has a comment-region feature. I would support adding a reader macro for raw strings, because that is an issue (almost every ns docstring is escaped), and if we had those, then multiline comments would be subsumed by them:
#_
#[[ ;; lua-like proposal for raw strings

]]
Hide
Lau Jensen added a comment -

If its a pressing issue or not isn't really the question is it?

To me its a straightforward patch which adds functionality currently not found in Clojure and which I personally would label a welcomed addition.

Show
Lau Jensen added a comment - If its a pressing issue or not isn't really the question is it? To me its a straightforward patch which adds functionality currently not found in Clojure and which I personally would label a welcomed addition.
Hide
Chouser added a comment -

Sure it adds a feature, but it also adds syntax and complexity to the language. If the feature it adds doesn't solve real problems of sufficient importance, it may be a net loss for the language.

For temporarily commenting out code, #_ and (comment ...) work fine. For hunks of documentation text, ; or ;; work nicely, especially if you have an ultra-advanced editor like vim to handle your text reformatting. Is there another use case?

Show
Chouser added a comment - Sure it adds a feature, but it also adds syntax and complexity to the language. If the feature it adds doesn't solve real problems of sufficient importance, it may be a net loss for the language. For temporarily commenting out code, #_ and (comment ...) work fine. For hunks of documentation text, ; or ;; work nicely, especially if you have an ultra-advanced editor like vim to handle your text reformatting. Is there another use case?
Hide
Fogus added a comment - - edited

I'm with Chouser on this. Additionally, I would add that the description of #_ is "The form following #_ is completely skipped by the reader." However, trying something like:

    (defn gimmie-pi []
      #_( TODO: validate the accuracy
                of the return value. )
      3)

currently throws an exception. Maybe the form should really be skipped by the reader and allow free form text? I don't know if this is the right answer, but I would feel more comfortable with that than a new reader macro.

Show
Fogus added a comment - - edited I'm with Chouser on this. Additionally, I would add that the description of #_ is "The form following #_ is completely skipped by the reader." However, trying something like:
    (defn gimmie-pi []
      #_( TODO: validate the accuracy
                of the return value. )
      3)
currently throws an exception. Maybe the form should really be skipped by the reader and allow free form text? I don't know if this is the right answer, but I would feel more comfortable with that than a new reader macro.
Hide
Alan Malloy added a comment -

I don't think that's possible, Fogus. If it's going to skip "a form", then it has to understand the syntax therein well enough to determine which closing paren matches up.

Show
Alan Malloy added a comment - I don't think that's possible, Fogus. If it's going to skip "a form", then it has to understand the syntax therein well enough to determine which closing paren matches up.
Hide
Fogus added a comment -

> which closing paren matches up

I'm sorry, I was not clear that I didn't expect my idea to provide the entire functionality of the proposed #| ... |#.

I don't see the utility in providing a whole new reader macro to allow mismatched embedded parentheses. I can kinda see the value in allowing things like `TODO:`, although I would probably just use #_() or comment and just make sure that my embedded comment was not malformed and ; otherwise.

Show
Fogus added a comment - > which closing paren matches up I'm sorry, I was not clear that I didn't expect my idea to provide the entire functionality of the proposed #| ... |#. I don't see the utility in providing a whole new reader macro to allow mismatched embedded parentheses. I can kinda see the value in allowing things like `TODO:`, although I would probably just use #_() or comment and just make sure that my embedded comment was not malformed and ; otherwise.
Hide
Rich Hickey added a comment -

I'm opposed. I don't think the benefit/complexity ratio (especially for tools) is high enough. We've done without for quite a while and no one's caught fire.

Show
Rich Hickey added a comment - I'm opposed. I don't think the benefit/complexity ratio (especially for tools) is high enough. We've done without for quite a while and no one's caught fire.
Hide
Chas Emerick added a comment -

Closed per request from Alan Malloy.

Show
Chas Emerick added a comment - Closed per request from Alan Malloy.

People

Vote (5)
Watch (1)

Dates

  • Created:
    Updated:
    Resolved: