Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
On Tue, Aug 11, 2009 at 12:42 PM, Jon Lang wrote: > jerry gay wrote: >> for the latest spec changes regarding this item, see >> http://perlcabal.org/svn/pugs/revision/?rev=27959. >> >> is everyone equally miserable now? ;) > > Already seen it. My latest points still stand, though: #`(...) is > still vulnerable to ambiguity relative to #..., whereas `#(...), > `#...#`, or (#...) don't share the same vulnerability. With the latest S26 proposal (and its new declarator blocks) in mind, I think that I would be happiest if embedded comments used the (#...) syntax. Reason: you still get the flexibility of choosing your own delimiters (unlike `#...#`), and you don't have to worry about where the = goes (unlike #`(...): is it #=`(...), #=(...), or #`(=...)? Likewise for `#(...)). -- Jonathan "Dataweaver" Lang
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
On 2009-Aug-11, at 1:38 pm, raiph mellor wrote: For a quick backgrounder, Larry had talked of reserving backtick for use as a user defined operator [1], Mark had suggested its use as a (tightly bound) comment [2], and James et al had suggested using it to declare units [3]. I'd like to see units, but as I've pondered it in the back of my mind, I've realised we don't need special symbols for them. A unit is just an object that has methods for converting to other units; sugar can be provided by postfix operators that cast their operand to the appropriate type: "42ft" calls "Unit::Length::Foot(42)". I've long been in Mark's camp about a lightweight and attractive docstring syntax being likely to be helpful for encouraging habits that would likely contribute to improved long term maintainability of code with comments, and was mulling that. Me too. It's not just making it easier to write documentation as you go -- and POD already makes it fairly easy -- but more than that, it's a matter of making it easier to *structure* that documentation. P6 is so powerful that equally powerful docs are going to be needed to take advantage of it. For example, there needs to be a way to pull out the docs for a specific function, or a specific parameter of a specific function: perldoc --module=Foo::Bar --method=baz --param=Title In P5, there's a sort of coincidental structure available, in that you can put a chunk of POD next the function it describes, but the relationship needs to be more formal if, say, your editor is to be able to pull out that information to display it when you click on a keyword, or to auto-complete argument names, etc. Happily, Damian posted a while back that he is working on a way to associate docs with code. The other problem related to that is the need for end-user documentation to have its own structure and order, which often will not be the same order supplied by the code. There needs to be a way to override and extend the structure, either by specifying a recipe for assembling the finished doc out of separate chunks of POD scattered about the code; or else by writing the docs in order and then link pieces the associated units of code. (Of course, we're also faced with a poverty of tools: there's no technical reason we couldn't view the same file in "code mode" and "doc mode"... but it's no fun writing features that people can't use. On the other hand, nobody writes tools for features that don't exist, so you have to start somewhere.) -David
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
jerry gay wrote: for the latest spec changes regarding this item, see http://perlcabal.org/svn/pugs/revision/?rev=27959. is everyone equally miserable now? ;) I'm quite happy actually -- #` or #+ makes no difference to me :-) S02 just got that little bit simpler, so the thread was worthwhile. Thank you O Great Decider!! Cheers -- smuj
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
jerry gay wrote: > for the latest spec changes regarding this item, see > http://perlcabal.org/svn/pugs/revision/?rev=27959. > > is everyone equally miserable now? ;) Already seen it. My latest points still stand, though: #`(...) is still vulnerable to ambiguity relative to #..., whereas `#(...), `#...#`, or (#...) don't share the same vulnerability. -- Jonathan "Dataweaver" Lang
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
> for the latest spec changes regarding this item, see > http://perlcabal.org/svn/pugs/revision/?rev=27959. > > is everyone equally miserable now? ;) > ~jerry Ha! :) I do indeed feel underwhelmed. I'll surely get over it but I may as well post why, even though Larry's presumably trying to stop the discussion. Sorry Larry. First, I had liked some of the ideas that had been posted in this thread. Quite a lot more than Larry's pick. Of course, I may well be missing complications he can see. Second, I had been mulling backtick, but was thinking on more radical lines than the one Larry's gone for. Again, perhaps he's got more up his sleeve that builds on what he's just committed. For a quick backgrounder, Larry had talked of reserving backtick for use as a user defined operator [1], Mark had suggested its use as a (tightly bound) comment [2], and James et al had suggested using it to declare units [3]. I've long been in Mark's camp about a lightweight and attractive docstring syntax being likely to be helpful for encouraging habits that would likely contribute to improved long term maintainability of code with comments, and was mulling that. -- love, raiph [1] http://markmail.org/message/zvn2hul6irggtrde [2] http://groups.google.com/group/perl.perl6.language/msg/7d10c6bc5d66288e?hl=en [3] http://www.mail-archive.com/perl6-language@perl.org/msg20819.html -- love, raiph
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
Ben Morrow wrote: > This appears to be leading to a :comment modifier on quotables, with > some suitable shortcut. Perhaps 'q#'? Or are we not allowed mixed alpha > and symbols? It's probably a bad practice, if possible. > (I really want to suggest £, just to teach USAnians '#' isn't called > 'pound'... :) ) In all seriousness, there's another use to which I'd like to put '£'. -- Jonathan "Dataweaver" Lang
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
for the latest spec changes regarding this item, see http://perlcabal.org/svn/pugs/revision/?rev=27959. is everyone equally miserable now? ;) ~jerry
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
At 6PM +0200 on 11/08/09 you (Moritz Lenz) wrote: > Ben Morrow wrote: > > > > However, I would much rather see a general syntax like > > > > (# ... ) > > {# ... } > > [# ... ] > > > > with no whitespace allowed between the opening bracket and the #: this > > doesn't seem to conflict with anything. Allowing <# ... > in rules would > > also be nice. > > That severely violates the principle of least surprise. To me [#...] > looks like an array ref which contains a comment, which is *not* what > you propose (I think). No, it wasn't. The idea was modelled after TT2's [%# ... %] syntax, and other languages that mark comments just inside the delimiters. > It also feels like a step backwards. In Perl 6 we try to make things > clear from the beginning, not only from the second char on. Regex > modifiers at the, anybody? or (?#...) as comments in regexes in Perl 5? > > In all other cases of quote like constructs are the semantics are > explicit first (think of Q, qx, m, <, «), the delimiter comes later. > Changing that all of a sudden seems very unintuitive and wrong. This appears to be leading to a :comment modifier on quotables, with some suitable shortcut. Perhaps 'q#'? Or are we not allowed mixed alpha and symbols? Ben (I really want to suggest £, just to teach USAnians '#' isn't called 'pound'... :) )
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
Moritz Lenz writes: > In all other cases of quote like constructs are the semantics are > explicit first (think of Q, qx, m, <, «), the delimiter comes later. > Changing that all of a sudden seems very unintuitive and wrong. Thing is, comments are not quote-like. All of the quote-like constructs are expressions. Comments are not. Different things should be different, and comments should not look like expressions. Or so it seems to me, at least. Rambling along ... In C++, all comments start with the same character, but it is the end-of-line comments that start off with it doubled up. And so C++ avoids these gotchas. Alternatively, if end-of-line comments required whitespace (or some other non-bracket non-# character class) after one or more # characters, it would not just resolve the gotchas: It would make the comments far easier to read as well. Meanwhile, a # sequence followed by neither whitespace nor brackets would be a syntax error, and I imagine that might make it hard to sell. Too late for Perl to go that way though. (Right? Yeah, right.) The only other way for Perl to avoid these gotchas and still retain the two kinds of comments seems to be if the two constructs start with different characters. Putting the delimiter first is one way of doing it. Reserving one more comment leading character would be another. Seems expensive though. :-\ So, are the more ways to design it with a different leading character? :#( ... ) has been suggested, and it is begginning to grow on me. :# ... #: could work, I suppose (it is not a quote-like expression, so doesn't need to look like it is) – but since the closer there starts with a #, I imagine that might run into similar trouble. An unspace-like \#( ... ) could perhaps work? ... though I get the feeling someone else has rambled along these lines before ... Eirik -- Ceci n'est pas une .sig.
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
Ben Morrow wrote: > Quoth markjr...@gmail.com (Mark J. Reed): >> >> I still like the double-bracket idea. I don't much mind the extra >> character; 5 characters total still beats the 7 of HTML/XML. > > I much prefer double-bracket to double-#: double-# gets caught out when > you do s/^/# on code which already includes line-starting # comments. > > However, I would much rather see a general syntax like > > (# ... ) > {# ... } > [# ... ] > > with no whitespace allowed between the opening bracket and the #: this > doesn't seem to conflict with anything. Allowing <# ... > in rules would > also be nice. That severely violates the principle of least surprise. To me [#...] looks like an array ref which contains a comment, which is *not* what you propose (I think). It also feels like a step backwards. In Perl 6 we try to make things clear from the beginning, not only from the second char on. Regex modifiers at the, anybody? or (?#...) as comments in regexes in Perl 5? In all other cases of quote like constructs are the semantics are explicit first (think of Q, qx, m, <, «), the delimiter comes later. Changing that all of a sudden seems very unintuitive and wrong. Cheers, Moritz
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
On Tue, Aug 11, 2009 at 8:59 AM, Jon Lang wrote: > Ben Morrow wrote: > > However, I would much rather see a general syntax like > > > >(# ... ) > >{# ... } > >[# ... ] > > > a preceding ':' (colon) makes it *notionally* a null-label-block-comment-construct. > > > with no whitespace allowed between the opening bracket and the #: this > > doesn't seem to conflict with anything. Allowing <# ... > in rules would > > also be nice. > > That's rather elegant. It's no longer than the current embedded > comment syntax, and avoids the start-of-line issue. The only > complication arises when you prepend the brackets with a quote or > pseudo-quote character: > > say q(# is this a string or a comment?); # DWIM -> string. > > -- > Jonathan "Dataweaver" Lang >
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
On Mon, Aug 10, 2009 at 10:31 AM, Carl Mäsak wrote: > In my post "Three things in Perl 6 that aren't so great" [0], I > outline three things about Perl 6 that bug me at present. Commenter > daxim made what seems to me a sensible proposal [1] for solving the > third problem, "Comments in the beginning of lines": > > daxim (]): > ] Let single # be used for commenting out, no matter what follows. > ] Let ## (perhaps also ### and so on) switch on the special behaviour > ] of brackets etc. > While I like the idea, ## occurs frequently in much existing code, a more selective pattern would help. like "#{" and "#}" - explicit, DWIM block constructs or qr/^\s*\#{3,}:[\[\{\(\<]/etc .. - multiple-sharps makes the comment-block more visible - any block-punctuation works (why limit it?) This would clash far less with existing code, and thus be usable there incrementally. And this makes it a more portable, POD++ ish feature.
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
Ben Morrow wrote: > However, I would much rather see a general syntax like > > (# ... ) > {# ... } > [# ... ] > > with no whitespace allowed between the opening bracket and the #: this > doesn't seem to conflict with anything. Allowing <# ... > in rules would > also be nice. That's rather elegant. It's no longer than the current embedded comment syntax, and avoids the start-of-line issue. The only complication arises when you prepend the brackets with a quote or pseudo-quote character: say q(# is this a string or a comment?); # DWIM -> string. -- Jonathan "Dataweaver" Lang
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
smuj wrote: > Jon Lang wrote: >> smuj wrote: >>> Jon Lang wrote: Here's a radical notion: use something other than '#' to initiate an inline comment. >>> [snippage] >>> >>> Or maybe just don't allow "embedded" comments unless they are actually >>> "embedded", i.e. if a line starts with a # (ignoring leading whitespace) >>> then it's _always_ a line-end comment, no matter what follows the #, e.g. >> >> That has the advantage of preserving a three-character embedded >> comment. It has the disadvantage that you get differing behavior >> depending on where the comment is on the line. As I see it, the whole >> point of this exercise is to get rid of the gotchas, and not just to >> shift them around - thus my ':#' proposal. > > I think whatever the solution is, it must begin with a # -- anything else > will likely create even more gotchas. When inline comments begin with a '#', the main gotcha arises when you go to comment out a series of lines by prepending a # to each, and one of those lines begins with the proper series of characters to create an inline comment instead. If you add the condition that a line beginning with a '#' is automatically a full-line comment (or, as currently specced, simply complains about the ambiguity), you replace this gotcha with one where someone types in what he intends to be an inline comment, but forgets to indent it. Adding a secondary character after the '#' reduces the likelihood of this happening, but doesn't eliminate it. When inline comments begin with something other than '#', none of the above gotchas exist. Instead, the main gotcha occurs when you go to create an end-of-line comment at the end of a line that ends with whatever the first character of an inline comment is. A programmer who forgets to put whitespace between that character and the '#' will get an inline comment instead. IMHO, this is no different than any other case where the programmer mistakenly allows two different tokens to run together. As well, when programmers add comments to the ends of a series of lines, they generally lead off with whitespace intended to align said comments with each other; so existing habits would not cause difficulties as they currently do for commenting out lines. > Also, we have to realize that no > matter what sequence we choose for embedded comments, there will _always_ be > a chance of a gotcha, so all we can do is minimize the likelihood, as well > as making the gotcha easy to spot, whilst not making embedded comments too > difficult to use for those who like them. My argument is that starting an inline comment with something other than a '#' minimizes the likelihood of gotchas, makes gotchas easy to spot, and doesn't make embedded comments too difficult to use for those who like them. Is there anything that my argument missed? > My current personal favourite would be to keep things as they are with > regards to bracketing, but to introduce a + between the # and the brackets. This reduces the likelihood of ambiguity cropping up between an embedded comment and an end-of-line comment; but it doesn't eliminate the possibility. Reversing the order to '+#' _would_ eliminate any possibility of ambiguity at the start of a line; and the only thing you'd have to watch out for would be someone deciding to start an end-of-line comment immediately after a '+', with no intervening whitespace. As well, '+#' is just as easy to type as '#+'. Heck, while I like the bracketing idea, you could even say that any comment that begins with '+#' followed immediately by a non-bracketing character is an inline comment that will be terminated by the first '#+' sequence it finds: #end-of-line comment #(end-of-line) comment #+end-of-line comment #+(end-of-line) comment +# embedded comment #+ +#(embedded comment) I'm not picky as to the choice of the additional character; but if you're going to add it in, add it in where it will cause the least amount of trouble: just before the '#'. > I'd also change the terminology from "embedded" comments to "extended" > comments. toMAYto, toMAHto. -- Jonathan "Dataweaver" Lang
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
Quoth markjr...@gmail.com (Mark J. Reed): > > I still like the double-bracket idea. I don't much mind the extra > character; 5 characters total still beats the 7 of HTML/XML. I much prefer double-bracket to double-#: double-# gets caught out when you do s/^/# on code which already includes line-starting # comments. However, I would much rather see a general syntax like (# ... ) {# ... } [# ... ] with no whitespace allowed between the opening bracket and the #: this doesn't seem to conflict with anything. Allowing <# ... > in rules would also be nice. Ben
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
Jon Lang wrote: smuj wrote: Jon Lang wrote: Here's a radical notion: use something other than '#' to initiate an inline comment. [snippage] Or maybe just don't allow "embedded" comments unless they are actually "embedded", i.e. if a line starts with a # (ignoring leading whitespace) then it's _always_ a line-end comment, no matter what follows the #, e.g. That has the advantage of preserving a three-character embedded comment. It has the disadvantage that you get differing behavior depending on where the comment is on the line. As I see it, the whole point of this exercise is to get rid of the gotchas, and not just to shift them around - thus my ':#' proposal. I think whatever the solution is, it must begin with a # -- anything else will likely create even more gotchas. Also, we have to realise that no matter what sequence we choose for embedded comments, there will _always_ be a chance of a gotcha, so all we can do is minimise the likelihood, as well as making the gotcha easy to spot, whilst not making embedded comments too difficult to use for those who like them. My current personal favourite would be to keep things as they are with regards to bracketing, but to introduce a + between the # and the brackets. I'd also change the terminology from "embedded" comments to "extended" comments. The + sign is a good mnemonic for "extended" IMHO. It's neither too much of a heavyweight nor too much of a lightweight. The +bracket sequence isn't "too" common -- or at least probably not where you might want to introduce a comment -- and it keeps "extended" comment syntax down to 4 characters, e.g. say #+( extended comment ) "hello, world!"; $object\#+{ extended comments }.say; $object\ #+「 extended comments 」.say; #sub foo# line-end comment #{ # ditto # ... # ditto again #} # what he said! #sub foo# line end comment #+{ # extended comment ... # extends } # to here Cheers -- smuj
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
smuj wrote: > Jon Lang wrote: >> Here's a radical notion: use something other than '#' to initiate an >> inline comment. >> > [snippage] > > Or maybe just don't allow "embedded" comments unless they are actually > "embedded", i.e. if a line starts with a # (ignoring leading whitespace) > then it's _always_ a line-end comment, no matter what follows the #, e.g. That has the advantage of preserving a three-character embedded comment. It has the disadvantage that you get differing behavior depending on where the comment is on the line. As I see it, the whole point of this exercise is to get rid of the gotchas, and not just to shift them around - thus my ':#' proposal. OTOH, you just (inadvertently?) pointed out that ':#<...>' is very much like adverbial syntax; this could be quite useful if we ever find a need for the parser to associate comments directly with code, in that anything that can take an adverb could theoretically have a comment associated with it. But that's a can of worms that doesn't need to be opened yet, if ever. > We could always have a Q form in place of #'s to achieve the above effect > from S02, more like a funny heredoc, e.g. > > Q :#<<< # embedded > sub foo # comment > { # extends > ... # to > } # (wait for it) # here! > > Maybe call it a "theredoc"! :-) We can already do this using POD sections: =begin comment sub foo { ... } =end comment I don't see much need for a #-based multi-line comment beyond this. But it _would_ be nice to be able to indent POD Sections in the same way that you can indent heredocs. Especially if the former is intended to be the standard means of commenting out blocks of lines. OTOH, let's say for the moment that we choose to extend the analogy between embedded comments and quotes: one could, in theory, do a Heredoc-style comment: :# <<< END line 1 line 2 line 3 END where ':#' is the comment-equivalent of 'q', whatever that turns out to be. (I'm not sold on ':#'; but I _would_ like to see a two-symbol token that begins with a non-'#' and ends with a '#', for conciseness and clarity.) Technically, this would also allow for the likes of ':#"comment"'. But I agree with the gentleman from the original discussion years ago that we should probably forbid non-bracketing characters when delimiting embedded comments. -- Jonathan "Dataweaver" Lang
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
Jon Lang wrote: smuj wrote: smuj wrote: Jon Lang wrote: ... the biggest potential stumbling block for this would be the existence of a double-bracket that sees frequent use at the start of a line. Query: does '<<' count as a double bracket, or as a single bracket (since it's equivalent to '«')? [S02] {Note however that bare circumfix or postcircumfix <<...>> is not a user-selected bracket, but the ASCII variant of the «...» interpolating word list. Only # and the q-style quoters (including m, s, tr, and rx) enable subsequent user-selected brackets.} Just to clarify on that quote from S02, what I was trying to say (if I understand the synopsis correctly) is that << counts as either single or double depending on context. If you stick a # on the front, then << will count as a double bracket. Thanks for the clarification. Either we change this so that '<<' counts as a single bracket for inline comment purposes, or we live with the risk of start-of-line inline comments '#<< ... >>' when prepending #'s to comment out sections of code. Or we leave it as is. Is it really _that_ big of a problem to retrain yourself to type "# " instead of "#" when commenting out lines? It would certainly annoy a lot of people, me included! :-) Here's a radical notion: use something other than '#' to initiate an inline comment. [snippage] Or maybe just don't allow "embedded" comments unless they are actually "embedded", i.e. if a line starts with a # (ignoring leading whitespace) then it's _always_ a line-end comment, no matter what follows the #, e.g. #blah # line-end comment #{ # another line-end comment #{ # yet another line-end comment (YALC) some-code-here #{...}# embedded comment If we allow the following coding style from S02: #sub foo# line end comment #{ # okay, comment ... # extends } # to here then perhaps we should change the term "embedded comment" to "extended comment". We could always have a Q form in place of #'s to achieve the above effect from S02, more like a funny heredoc, e.g. Q :#<<< # embedded sub foo # comment { # extends ...# to } # (wait for it) >>> # here! Maybe call it a "theredoc"! :-) Cheers -- smuj
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
Darren Duncan wrote: > Still, I like the idea of #...# also being supported from the point of > symmetry with '...' and "..." also being supported, not that this is > necessary. This is mutually exclusive with the practice of commenting out a bunch of lines by prepending them with '#'. -- Jonathan "Dataweaver" Lang
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
smuj wrote: > smuj wrote: >> Jon Lang wrote: >>> ... the biggest potential stumbling block for this >>> would be the existence of a double-bracket that sees frequent use at >>> the start of a line. Query: does '<<' count as a double bracket, or >>> as a single bracket (since it's equivalent to '«')? If the former, >>> then there's a respectable chance of seeing a line that begins with >>> '<<' which would comment out as an inline comment rather than an >>> end-of-line comment. If the latter, lines beginning with '<<' would >>> still comment out as end-of-line comments. Off the top of my head, I >>> can't think of any other bracketing characters that are commonly >>> doubled up. >> >> [S02] {Note however that bare circumfix or postcircumfix <<...>> is not a >> user-selected bracket, but the ASCII variant of the «...» interpolating word >> list. Only # and the q-style quoters (including m, s, tr, and rx) enable >> subsequent user-selected brackets.} > > Just to clarify on that quote from S02, what I was trying to say (if I > understand the synopsis correctly) is that << counts as either single or > double depending on context. If you stick a # on the front, then << will > count as a double bracket. Thanks for the clarification. Either we change this so that '<<' counts as a single bracket for inline comment purposes, or we live with the risk of start-of-line inline comments '#<< ... >>' when prepending #'s to comment out sections of code. Or we leave it as is. Is it really _that_ big of a problem to retrain yourself to type "# " instead of "#" when commenting out lines? Here's a radical notion: use something other than '#' to initiate an inline comment. I suggested before the possibility of '#:' as the inline comment identifier; what if we reverse this, and require ':#' instead? This would completely remove the risk of a start-of-line comment being confused with an inline comment. It would be visially lightweight. It would be short (four characters minimum). It wouldn't require you to double up on anything. And the only danger would be if you try to insert a comment immediately after a colon, with no intervening whitespace - which strikes me as an _extremely_ bad practice which should be discouraged regardless. So: # line comment #(line comment) :# syntax error (missing brackets) :#(inline comment) -- Jonathan "Dataweaver" Lang
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
Jon Lang wrote: On Mon, Aug 10, 2009 at 3:36 PM, Darren Duncan wrote: Personally, I think that comments should have trailing # as well as leading ones, so they are more like strings in that the same character is used to mark both ends. You mean like the following? q[quoted text] qq(interpolated quote) s = "string" rx(pattern) The leading # in an inline comment is akin to the q|qq|s|tr etc. of the various pseudo-quote structures: it identifies to what purpose the brackets are being used. Yes, it is like you say. A trailing # would be superfluous. Okay, you make a point that the likes of q[] probably outweigh the use of '' or "" in non-trivial strings. Note that my proposal is orthogonal to other issues like double-leading # or whatever bracketing chars are used. Also note that if the # are treated more like delimiters, then potentially we could also have \# to escape literal #, same as we have \' or \" etc. Ugh. One of the reasons for the likes of q< ... >, etc. is to provide an alternative to having to escape the delimiter by allowing you to select a delimiter that won't clash. By making '#' a delimiter, you remove that ability. Still, I like the idea of #...# also being supported from the point of symmetry with '...' and "..." also being supported, not that this is necessary. On the other hand, if #...# were supported, I would still also want Perl to DWIM when one uses a line of hash-marks for a visual divider line, like ## (to 80 chars or something). -- Darren Duncan
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
smuj wrote: Jon Lang wrote: On Mon, Aug 10, 2009 at 2:16 PM, Mark J. Reed wrote: I still like the double-bracket idea. I don't much mind the extra character; 5 characters total still beats the 7 of HTML/XML. Agreed. As I said, the biggest potential stumbling block for this would be the existence of a double-bracket that sees frequent use at the start of a line. Query: does '<<' count as a double bracket, or as a single bracket (since it's equivalent to '«')? If the former, then there's a respectable chance of seeing a line that begins with '<<' which would comment out as an inline comment rather than an end-of-line comment. If the latter, lines beginning with '<<' would still comment out as end-of-line comments. Off the top of my head, I can't think of any other bracketing characters that are commonly doubled up. [S02] {Note however that bare circumfix or postcircumfix <<...>> is not a user-selected bracket, but the ASCII variant of the «...» interpolating word list. Only # and the q-style quoters (including m, s, tr, and rx) enable subsequent user-selected brackets.} Just to clarify on that quote from S02, what I was trying to say (if I understand the synopsis correctly) is that << counts as either single or double depending on context. If you stick a # on the front, then << will count as a double bracket. Cheers, -- smuj
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
On Mon, Aug 10, 2009 at 3:36 PM, Darren Duncan wrote: > Personally, I think that comments should have trailing # as well as leading > ones, so they are more like strings in that the same character is used to > mark both ends. You mean like the following? q[quoted text] qq(interpolated quote) s = "string" rx(pattern) The leading # in an inline comment is akin to the q|qq|s|tr etc. of the various pseudo-quote structures: it identifies to what purpose the brackets are being used. A trailing # would be superfluous. > Note that my proposal is orthogonal to other issues like double-leading # or > whatever bracketing chars are used. > > Also note that if the # are treated more like delimiters, then potentially > we could also have \# to escape literal #, same as we have \' or \" etc. Ugh. One of the reasons for the likes of q< ... >, etc. is to provide an alternative to having to escape the delimiter by allowing you to select a delimiter that won't clash. By making '#' a delimiter, you remove that ability. -- Jonathan "Dataweaver" Lang
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
As an addendum, I think it goes without saying that this is the simplest form of what I proposed: # This is a comment. # That denotes a complete comment, which could be broken over lines or not, and the rules for parsing or escaping it would be exactly the same as a character string literal, except for a lack of interpolation abilities, and literal # are escaped. That is essentially how I do comments in Muldis D, and it works quite well. -- Darren Duncan Darren Duncan wrote: Personally, I think that comments should have trailing # as well as leading ones, so they are more like strings in that the same character is used to mark both ends. So in combination with bracketing pairs, we could for example have this: #{ This is a comment. }# That also serves to make the comments more whitespace independent, like with strings in general. I think the trailing # may also resolve some other issues raised in this thread. Note that my proposal is orthogonal to other issues like double-leading # or whatever bracketing chars are used. Also note that if the # are treated more like delimiters, then potentially we could also have \# to escape literal #, same as we have \' or \" etc. Having # at both ends makes it easier to see at a glance where comments begin and end, and potentially it makes it easier to make a parser or syntax colorer.
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
Personally, I think that comments should have trailing # as well as leading ones, so they are more like strings in that the same character is used to mark both ends. So in combination with bracketing pairs, we could for example have this: #{ This is a comment. }# That also serves to make the comments more whitespace independent, like with strings in general. I think the trailing # may also resolve some other issues raised in this thread. Note that my proposal is orthogonal to other issues like double-leading # or whatever bracketing chars are used. Also note that if the # are treated more like delimiters, then potentially we could also have \# to escape literal #, same as we have \' or \" etc. Having # at both ends makes it easier to see at a glance where comments begin and end, and potentially it makes it easier to make a parser or syntax colorer. -- Darren Duncan
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
Jon Lang wrote: On Mon, Aug 10, 2009 at 2:16 PM, Mark J. Reed wrote: I still like the double-bracket idea. I don't much mind the extra character; 5 characters total still beats the 7 of HTML/XML. Agreed. As I said, the biggest potential stumbling block for this would be the existence of a double-bracket that sees frequent use at the start of a line. Query: does '<<' count as a double bracket, or as a single bracket (since it's equivalent to '«')? If the former, then there's a respectable chance of seeing a line that begins with '<<' which would comment out as an inline comment rather than an end-of-line comment. If the latter, lines beginning with '<<' would still comment out as end-of-line comments. Off the top of my head, I can't think of any other bracketing characters that are commonly doubled up. [S02] {Note however that bare circumfix or postcircumfix <<...>> is not a user-selected bracket, but the ASCII variant of the «...» interpolating word list. Only # and the q-style quoters (including m, s, tr, and rx) enable subsequent user-selected brackets.} Cheers, -- smuj
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
On Mon, Aug 10, 2009 at 2:16 PM, Mark J. Reed wrote: > I still like the double-bracket idea. I don't much mind the extra > character; 5 characters total still beats the 7 of HTML/XML. Agreed. As I said, the biggest potential stumbling block for this would be the existence of a double-bracket that sees frequent use at the start of a line. Query: does '<<' count as a double bracket, or as a single bracket (since it's equivalent to '«')? If the former, then there's a respectable chance of seeing a line that begins with '<<' which would comment out as an inline comment rather than an end-of-line comment. If the latter, lines beginning with '<<' would still comment out as end-of-line comments. Off the top of my head, I can't think of any other bracketing characters that are commonly doubled up. -- Jonathan "Dataweaver" Lang
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
On Mon, Aug 10, 2009 at 4:57 PM, Jon Lang wrote: > I'd recommend '#='; but if that > isn't already being used by pod, it should be reserved for use by pod > (and it's visually heavy). Commenting out lines that include pod will generate #= at the beginning of a line, which is tantamount to the problem we're trying to avoid. > What other symbols are reasonably easy to type, are visually > lightweight, and are unlikely to be found at the start of a line and > immediately followed by an open bracket? Hmm... how about '#.'? Too visually lightweight, IMO Almost disappears entirely in this font next to the heavy #, making the third and fourth lines below easily confusable. > #line comment > #.line comment > #(line comment) > #.(inline comment) Besides which, Perl 6 teaches us that $foo() and $foo.() are usually interchangeable. :) I still like the double-bracket idea. I don't much mind the extra character; 5 characters total still beats the 7 of HTML/XML. -- Mark J. Reed
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
On Mon, Aug 10, 2009 at 12:25 PM, Patrick R. Michaud wrote: > I'd be fine with the ##(embedded comment solution) approach (doubling > the #'s), but it's much less visually appealing to me. I think I'd > prefer to see a doubling of the bracketing chars instead of doubling > the #'s -- the # is visually a "heavy" glyph and I'd prefer > something a bit lighter. > > #((embedded comment)) > #{{embedded comment}} I could definitely go with this. The only question lies in how often you're likely to find a doubled open-bracket at the start of a line. However, let me toss out some other possibilities for consideration: If you want lightweight, another possibility would be to insist that an inline comment must be preceded by horizontal whitespace; so "#{ comment }" would be an end-of-line comment, whereas " #{ comment }" would be an inline comment. This is in keeping with the current spec's use of whitespace to distinguish between a start-of-line comment and an inline comment. Then again, perhaps that's a bit _too_ lightweight. And it adds to another problem that I have with Perl 6, namely the variety of mandatory/forbidden whitespace rules. They are, IMHO, a necessary evil, and should be kept to a minimum. Plus, when I typed the latter one out in this message, the composition window wrapped the line between the start of the quote and the #. One of the lesser purposes of an inline comment is when you're passing code through channels that might insert word-wraps into the code: an end-of-line comment has the possibility of breaking, whereas the inline comment handles it without complaint. Another possibility: instead of "##" for an inline comment, how about some other two-character pair that starts with a '#', where the second character is a non-bracketing character that's unlikely to be found at the start of a line? E.g., '#:' - the colon is visible, lightweight, and is almost always tacked onto the end of something else. In this approach, the minimum number of characters needed for an inline comment will be four: the '#:' pair, an open-bracket, and a close-bracket. (Compare to '#{{ ... }}', which requires a minimum of five characters.) It also avoids the question of how much repetition of the '#' is permitted. So: #line comment #:line comment #(line comment) #:(inline comment) OTOH, :( ... ) is the Perl syntax for a signature; and it wouldn't be unreasonable to find a signature at the beginning of a line. Far less common than the current situation of finding an open-bracket there; but perhaps too common to ignore. I'd recommend '#='; but if that isn't already being used by pod, it should be reserved for use by pod (and it's visually heavy). What other symbols are reasonably easy to type, are visually lightweight, and are unlikely to be found at the start of a line and immediately followed by an open bracket? Hmm... how about '#.'? #line comment #.line comment #(line comment) #.(inline comment) -- Jonathan "Dataweaver" Lang
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
Patrick R. Michaud wrote: On Mon, Aug 10, 2009 at 06:46:34PM +0100, smuj wrote: Although I can see some minimal uses for embedded comments, I think in general the cost/benefit ratio isn't enough to warrant their existence. I could be wrong of course! :-) I'd like to know if anyone has made much use of them in their code, and under what circumstances. I've used embedded comments a number of times (especially in examples) and found them to be incredibly useful. I'd be sad to see them disappear. I'd be fine with the ##(embedded comment solution) approach (doubling the #'s), but it's much less visually appealing to me. I think I'd prefer to see a doubling of the bracketing chars instead of doubling the #'s -- the # is visually a "heavy" glyph and I'd prefer something a bit lighter. #((embedded comment)) #{{embedded comment}} Pm Yep, I agree that #((blah)) is better than ##(blah). It's much easier to pick out and far more difficult to create by mistake, so it satisfies my notion of being "purposeful", whilst also lessening the possibility of "gotchas"! It's also better because it's already valid embedded comment syntax: [S02] {For all quoting constructs that use user-selected brackets, you can open with multiple identical bracket characters, which must be closed by the same number of closing brackets} The "special rule" disallowing embedded comments as the first thing on a line could be done away with, easing the learning curve of those new to the language, so this seems like a good idea all round -- unless you're the poor soul who has to change the grammar yet again! ;-) Cheers, -- smuj
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
On Mon, Aug 10, 2009 at 06:46:34PM +0100, smuj wrote: > Although I can see some minimal uses for embedded comments, I think in > general the cost/benefit ratio isn't enough to warrant their existence. > I could be wrong of course! :-) I'd like to know if anyone has made much > use of them in their code, and under what circumstances. I've used embedded comments a number of times (especially in examples) and found them to be incredibly useful. I'd be sad to see them disappear. I'd be fine with the ##(embedded comment solution) approach (doubling the #'s), but it's much less visually appealing to me. I think I'd prefer to see a doubling of the bracketing chars instead of doubling the #'s -- the # is visually a "heavy" glyph and I'd prefer something a bit lighter. #((embedded comment)) #{{embedded comment}} Pm
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
Hiyas, Carl Mäsak wrote: In my post "Three things in Perl 6 that aren't so great" [0], I outline three things about Perl 6 that bug me at present. Commenter daxim made what seems to me a sensible proposal [1] for solving the third problem, "Comments in the beginning of lines": daxim (]): ] Let single # be used for commenting out, no matter what follows. ] Let ## (perhaps also ### and so on) switch on the special behaviour ] of brackets etc. I just want to say that this makes sense to me, both from a Huffmanian standpoint, and from the standpoint of the principle of least surprise. It doesn't make embedded comments much more convenient, because C<##(this)> isn't much more cumbersome to write than C<#(this)>. And it solves the commenting-out-whole-lines problem. Although I can see some minimal uses for embedded comments, I think in general the cost/benefit ratio isn't enough to warrant their existence. I could be wrong of course! :-) I'd like to know if anyone has made much use of them in their code, and under what circumstances. If they are to remain, I'd vote for the ## solution (as suggested by daxim) in order to remove the "gotchas" that are bound to occur otherwise. Embedded comments should be a "purposeful" thing! I wouldn't go for "any string of #'s longer than one" as that would require people to scan every line of #'s just to see if there was something on the other #(end) after an embedded comment. In the aftermath of YAPC::EU, the question of embedded comments was also touched upon, and another solution was discussed: leave things as they are currently specced, but don't consider C<#{> the start of an embedded comment -- in other words, all other bracketing characters can still be used to make embedded comments, but the curly braces can not. This, if I remember the discussions correctly, had two advantages: 1. It makes it safe(r) for the user to think 'closure' when she sees a C<{...}> block. Even in interpolated strings, it's a closure. 2. At least parts of the commenting-out-whole-lines problem would go away. It's not worth the complication IMHO. I would vote, in order of preference: 1) get rid of embedded comments altogether 2) ## followed by _any_ opening bracket character is an embedded comment It would be nice to hear p6l-ers' reactions on these two proposals. Be warned, though -- this is a bit of a bikeshedding topic. :) Every one and his dog is an expert on comment syntax. I think that's something we can all agree on!! :-) [0] http://use.perl.org/~masak/journal/39334 [1] http://use.perl.org/comments.pl?sid=43438&cid=69583 Cheers -- smuj