[R] Block comments in R?

[Duncan Murdoch]

On 10/9/2006 7:58 PM, Richard A. O'Keefe wrote:
> 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.

I think you're communicating fine, just failing to convince.  You give 
examples below where block comments in various languages can give 
unexpected results.  But I can construct examples in R where prefix 
comments give results that are hard to predict unless you know the 
parser very well.  For example:

a <- "this string contains
# five
words"

Does it really contain five words, or just four?  I wouldn't recommend 
using code like that, but if I were writing it in a syntax-highlighting 
editor that actually worked, it would be very clear to me what the 
answer was.  As would the examples you give below.  Sometimes block 
comments fail to correctly surround arbitrary text, but as long as the 
user receives immediate feedback, this isn't really a problem.

Duncan Murdoch


> 
> 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.
> 
> ______________________________________________
> R-help at 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.