http://dev.clojure.org/jira This file is an XML representation of an issue en-us 4.4 649 25-07-2011 http://dev.clojure.org/jira/browse/CLJ-714 Clojure <p>The (comment) macro is not a viable substitute for real multi-line comments:</p> <ul class="alternate" type="square"> <li>It evaluates to nil, so isn't really useful except at the top level</li> <li>It requires proper paren/etc nesting inside itself</li> <li>Contents must be valid tokens; for example TODO: is illegal inside a (comment)</li> </ul> <p>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.</p> <p>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.</p> CLJ-714

Real multi-line comments

Enhancement Minor Closed Declined Unassigned Alan Malloy Tue, 11 Jan 2011 23:53:50 -0600 Sat, 3 Sep 2011 22:05:50 -0500 Sat, 3 Sep 2011 22:05:50 -0500 5 1 <p>I am totally for this. I agree that comment isn't a valid substitution. comment is useless for a lot of things.</p> <p>Nice - but are you sure just doing nothing on an unexpected EOF is a good idea?<br/> 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.</p> <p>What about <tt>#_(...)</tt>?</p> <p>I know that the parens have to be balanced, but other than that, doesn't it do everything else?</p> <p>No.</p> <div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent"> <pre>user=&gt; #_(TODO: Hi there!) java.lang.Exception: Invalid token: TODO: </pre> </div></div> <p>And then, as you mentioned, we have the paren balance problem. The idea is to have something <b>completely</b> ignores what is inside of it.</p> <p>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.</p> <p>Revised patch attached, and using git format-patch now that I know it exists.</p> <p>You can use #_ with string literals already:</p> <div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent"> <pre>#_"TODO: Hi there!" </pre> </div></div> <p>The only problem we have is that we don't have raw strings. I don't think that we need another litrals for comments.</p> <p>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 &amp; 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).</p> <p>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. </p> <p>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'.</p> <p>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.</p> <p>Curiosity: wouldn't this be useful for literate programming tools?</p> <p>Rich: if you are interested in this assign to me and I will screen.</p> <p>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.</p> <p>I would support adding a reader macro for raw strings, because <em>that</em> is an issue (almost every ns docstring is escaped), and if we had those, then multiline comments would be subsumed by them:</p> <div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent"> <pre>#_ #[[ ;; lua-like proposal for raw strings ]] </pre> </div></div> <p>If its a pressing issue or not isn't really the question is it? </p> <p>To me its a straightforward patch which adds functionality currently not found in Clojure and which I personally would label a welcomed addition.</p> <p>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.</p> <p>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?</p> <p>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:</p> <div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent"> <pre> (defn gimmie-pi [] #_( TODO: validate the accuracy of the return value. ) 3) </pre> </div></div> <p>currently throws an exception. Maybe the form should <b>really</b> 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.</p> <p>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.</p> <p>&gt; which closing paren matches up</p> <p>I'm sorry, I was not clear that I didn't expect my idea to provide the entire functionality of the proposed #| ... |#. </p> <p>I don't see the utility in providing a whole new reader macro to allow mismatched embedded parentheses. I can <b>kinda</b> 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.</p> <p>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.</p> <p>Closed per request from Alan Malloy.</p> Global Rank Patch Code and Test