Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
On Tue, Aug 11, 2009 at 12:42 PM, Jon Langdatawea...@gmail.com 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
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
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
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
On Mon, Aug 10, 2009 at 10:31 AM, Carl Mäsak cma...@gmail.com 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:
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
Moritz Lenz mor...@faui2k3.org 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
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
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 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
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
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
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=43438cid=69583
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
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 12:25 PM, Patrick R. Michaudpmich...@pobox.com 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
On Mon, Aug 10, 2009 at 4:57 PM, Jon Langdatawea...@gmail.com 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 markjr...@gmail.com
Re: Embedded comments: two proposed solutions to the comment-whole-lines problem
On Mon, Aug 10, 2009 at 2:16 PM, Mark J. Reedmarkjr...@gmail.com 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
Jon Lang wrote:
On Mon, Aug 10, 2009 at 2:16 PM, Mark J. Reedmarkjr...@gmail.com 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
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
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
On Mon, Aug 10, 2009 at 3:36 PM, Darren Duncandar...@darrenduncan.net 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) spattern = 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
smuj wrote:
Jon Lang wrote:
On Mon, Aug 10, 2009 at 2:16 PM, Mark J. Reedmarkjr...@gmail.com 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
Jon Lang wrote: On Mon, Aug 10, 2009 at 3:36 PM, Darren Duncandar...@darrenduncan.net 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) spattern = 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:
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
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
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
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
