<< Back to previous view

[CLJ-714] Real multi-line comments Created: 11/Jan/11  Updated: 03/Sep/11  Resolved: 03/Sep/11

Status: Closed
Project: Clojure
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Enhancement Priority: Minor
Reporter: Alan Malloy Assignee: Unassigned
Resolution: Declined Votes: 5
Labels: None

Attachments: File 0001-Add-multi-line-comments.diff     Text File patch.txt    
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.



 Comments   
Comment by Anthony Simpson [ 11/Jan/11 11:56 PM ]

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

Comment by Benjamin Teuber [ 13/Jan/11 6:09 AM ]

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.

Comment by G. Ralph Kuntz, MD [ 13/Jan/11 8:19 AM ]

What about #_(...)?

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

Comment by Anthony Simpson [ 13/Jan/11 8:35 AM ]

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.

Comment by Alan Malloy [ 13/Jan/11 1:13 PM ]

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.

Comment by a_strange_guy [ 13/Jan/11 4:02 PM ]

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

Comment by Anthony Simpson [ 13/Jan/11 4:20 PM ]

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?

Comment by Stuart Halloway [ 14/Jan/11 7:18 AM ]

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

Comment by a_strange_guy [ 14/Jan/11 11:41 PM ]

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

]]
Comment by Lau Jensen [ 15/Jan/11 7:26 AM ]

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.

Comment by Chouser [ 24/Jan/11 9:40 AM ]

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?

Comment by Fogus [ 24/Jan/11 9:59 AM ]

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.

Comment by Alan Malloy [ 24/Jan/11 11:21 AM ]

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.

Comment by Fogus [ 24/Jan/11 11:40 AM ]

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

Comment by Rich Hickey [ 26/Jan/11 7:12 AM ]

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.

Comment by Chas Emerick [ 03/Sep/11 10:05 PM ]

Closed per request from Alan Malloy.

Generated at Fri Aug 01 17:38:17 CDT 2014 using JIRA 4.4#649-r158309.