[R] Block comments in R?

[Richard A. O'Keefe]

I wrote:
    > R is, and should remain, editor-neutral.
    > Amongst other things, it should NOT acquire misfeatures
    > in order to support editors that happen not to support comment-region.
    > Block comments are indeed editor-neutral,
    > but they do not solve any problem that R currently has,
    > and they ARE in practice highly error-prone.

Apparently I am *still* failing to communicate, because
Duncan Murdoch <murdoch at stats.uwo.ca> replied:
	I think they are only error-prone in editors that don't recognize them 
	and highlight them as comments.

There is indeed an error-proneness to do with syntax highlighting
in editors (specifically vim).  However, since "block COMMENTS" are COMMENTS,
then an editor that DOES recognise them SHOULD highlight them as comments.
(Because that's what they are.)

But the really major error-proneness I was speaking of has nothing to do
with editors or highlighting.  It is the simple fact that people *will*
try to use block comments to comment out code, and they just plain don't
*work* for that job.  And part of the problem is that people are trying
to tackle two very different tasks with the same tool.

Text task:
    Attach a large amount of commentary to a chunk of code,
    the commentary being in some notation *other than* the programming
    language the commentary is embedded in.

    For this task, something like
	/* ...
	   ...
	   ...
	*/
    is quite attractive.  Some people think it is better to do
	/* ...
	 * ...
	 * ...
	 */
    but if you are willing to put cruft at the beginning of each
    line, why aren't you willing to use end-of-line comments for this
    purpose?

    Block comments do not work reliably for the text task.  In fact,
    this is really _the_ major reason why syntax highlighting exists.
    Precisely because the notation in which the comments are written
    is *not* the programming language the commentary is embedded in,
    that notation (be it English, Tagalog, or Etruscan) has no
    particular reason to avoid the magic closing sequence.

    This was a nightmare in Algol 60 (where one form of comment, by no
    means the only one, used 'comment' and ';') because ';' was a very
    natural thing to put in English (French, Dutch, ...) text.

    It remains a nightmare in C, where one often has occasion to talk
    about files, and of course $LIB/*/*.R is a perfectly natural thing
    to want to mention in a comment.

Code task:
    Given a chunk of code which is temporarily unwanted, hide it from
    the compiler so that it will not be compiled, but leave it present
    in the source file so that it can quickly be recovered.

    If you use the *same* block comment brackets for this task as for
    the text task, and if comment brackets do not nest (as they do not
    in PL/I, Pascal, C, ...) then you are in immediate trouble, because
    you cannot use /* ... */ to comment out a chunk of code that contains
    either a text task comment or a code task comment.

    If comment brackets do nest, as they do in ML (*...*), Haskell {-...-},
    and Common Lisp #|...|# then you are still in trouble, because nothing
    prevents the code you are trying to comment out containing the magic
    delimiter in a string.  For example, if you try to comment out
	(defvar magic-end "|#")
    in Common Lisp, you get
	#|(defvar magic-end "|#")|#
	                     ^^
    which ends too soon.  (It is also a problem if the magic starter is
    inside a string.)

    To fix this, when the processor processes a nesting comment, it needs
    to understand that it IS processing programming-language text, so that
    it can safely skip strings.  But then you cannot use the *same*
    block comments for the code and text tasks.

So if you want to use block comments for the text task, you need
 - nesting comment brackets
 - which are distinct from the brackets used for textual comments.

This is one of the few things that C gets right, although a sickening
number of C programmers get it wrong.  C has /*..*/ for the text task
and #if 0 .... #endif for the code task.  The standard says clearly that
the stuff bracketed by #if 0 ... #endif is code, not text.

So anyone who wants to add block comments to R had better figure out
exactly _why_ they want to do this, because if they really want to handle
both the text task and the code task the comment system they end up with
will NOT be one that is familiar to most programmers.  (As noted, most C
programmers haven't really understood that /*...*/ shouldn't be used for
code.)

	R source code is mostly C, which only supports block comments (using the 
	strict compiler options we use);

End-of-line comments were added to C++, and subsequently to C99 (hey, it's
seven years since C99 came out; haven't we waited long enough for this Rachel?)
because block comments are so broken.