[xquery-talk] Smiley comments

[Michael Kay]

> 
> Can anyone enlighten EChan42 and the seemingly endless stream, in many different languages, of tweets about this lovable aspect of XQuery?
> 

For the record, here are edited highlights of the discussion which took place between 2nd and 6th December 2002:

Jeni Tennison, 2 Dec 2002:

The use of "--" in comment syntax in XPath 2.0 means that XSLT users
will find it harder to comment-out sections of their code for
debugging purposes (since XML comments cannot contain '--').

Michael Kay:

Ouch… Just when Scott had persuaded everyone that we needed to support nested
comments!

Unfortunately, the choice of comment delimiters is one of those things that
is both completely arbitrary and highly emotional at the same time. It's not
going to be easy to come up with an alternative that a majority prefer.

I've always felt that the way one ought to handle this is to make a list of
the options (one of which is the status quo) and ask people to put them in
order of preference.

Here's a candidate:

{| .... |}

Jim Melton:

I'm a huge fan of nested comments, which is highly useful when one needs to 
comment out a chunk of code that might already contain comments...

I am not rabid about the specific syntax of the comments though.  Mike's 
suggestion of {|...|} is acceptable, although I find myself sighing at the 
"new language, new comment syntax" syndrome ;^}  It'd be nice if we could 
find a comment syntax from some other popular language that would 
work. 

Michael Kay:

I chose on the following criteria:

* don't use any new characters
* choose opening and closing sequences that are different
* choose opening and closing sequences that "complement" each other
* chose an opening sequence that can't appear at the start of an expression

{* ... *} fails the last test: a valid query today is:

    <a> {*:b/b:*} </a>

The fact is, it's very hard for us to use the comment syntax of existing
language because we use common punctuation characters such as "/" and "*" in
rather unusual ways.

Jeni Tennison:

The survey at:

  
http://merd.net/pixel/language-study/syntax-across-languages/Vrs.html


Shows the following syntax for multi-line comments:

1. (* ... *)  Beta, Modula-3, OCaml, Pascal, SML
2. /* ... */  Dylan, Oz, B, C, C#, C++, Java, JavaScript, Mercury, PHP, PL/I
3. "  ...  "  Smalltalk
4. {  ...  }  Pascal
5. (  ...  )  Forth
6. {- ... -}  Haskell
7. #| ... |#  Common Lisp

Using Mike Kay's criteria:

> * don't use any new characters
> * choose opening and closing sequences that are different
> * choose opening and closing sequences that "complement" each other
> * chose an opening sequence that can't appear at the start of an expression

1, 2, 3, 4, 5 and 6 are out because they all fail on at least the
last of these. Common Lisp's #|...|# fails on the first of the
criteria -- it introduces #.

I think that we should avoid any syntax that starts/ends with {
because of the problems with that syntax being used at the start/end
of an attribute value template.

What about using colons in some way? They're existing characters that
can't appear at the start or end of an expression (any more, as far as
I can tell). For example:

  (: comment :)
  /: comment :/
  |: comment :|
  :- comment -:

Jonathan Robie:

I like either of the following:

   (:  comment  :)
   {:  comment  :}

I think I prefer the first. It looks cheerful with those happy faces on 
both sides.

Jim Melton:

I find that I like the first and the last better than the middle two, the 
|: ... :| alternative next, and the /: ... :/ alternative the least.

Scott Boag:

> > >   (: comment :)

I like this best, I guess.  The characters are a bit closer together on the
keyboard than the alternatives.

Michael Rys:

Note that we decided to use {} for XQuery specific delimiters:

{ EXPR }
{!-- Comment --}

So unless the new comment delimiter starts with { I am not interested.

Jeni Tennison:

I'd be very happy if it were the case that {}s were, indeed,
XQuery-specific delimiters, but currently they're used in both
comments and the validate expression in XPath as well as XQuery.

I'd prefer XPath not to include any {}s because I think that XSLT
users will find {}s in XPaths confusing given that they're used in
attribute value templates with a different meaning.

NOTE:

I haven’t been able to find the minutes of the meeting where the final decision was taken; they may contain further discussion. (The search facility for W3C mailing lists is notoriously poor.)

Michael Kay
Saxonica