Re: [R] Block comments in R?

From: Richard A. O'Keefe <ok_at_cs.otago.ac.nz>
Date: Mon 09 Oct 2006 - 23:58:59 GMT


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@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

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.



R-help@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code. Received on Tue Oct 10 10:04:54 2006

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.1.8, at Tue 10 Oct 2006 - 02:30:09 GMT.

Mailing list information is available at https://stat.ethz.ch/mailman/listinfo/r-help. Please read the posting guide before posting to the list.