[R] How to comment in R

[Wacek Kusnierczyk]

Greg Snow wrote:
> If it is fairly trivial to implement then go ahead and implement it, patches are always welcome.  

now that's *not* true.  not so long ago i submitted a patch improving on
Prof Brian Ripley's ad hoc fix to grep, and it was silently ignored.

in general, it should be fairly trivial for someone who knows the source
code.  having seen some of r's internals i must admit that it may indeed
not be a simple task.  but if you provide support -- specifically, tell
me which files are relevant for the fix -- i will be (relatively) happy
to look into it, should this be helpful to the community.


> But make sure that it does all that is intended and does it properly, I don't think this is as trivial as it first appears.
>   

agreed, in r many things are not as trivial as they first appear.

> The =pod and =cut of Perl is simple (but was not originally intended as just comments), but this is limited to the "here is documentation" type comments, not the "skip this code" type comments (since the = needs to be the first thing on a line).  You also run into problems if a space accidently inserted before the = and you cannot comment out part of a line.
>   

i don't think the users ask for something as general as include-anywhere
c-style comments.  a compromise would be to have specific tags (e.g.,
'#start' and '#end' as in the sed example i've posted) delimit block
comments if they appear as the first non-whitespace characters on a
line.  it's pretty convenient, but does not require sophisticated
parsing exceptions.  and they are still comments in themselves, just
that a user would have to be aware that #start-#end would comment out a
block, and that an unmatched #start or #end would (or not, depending on
the design choice) cause a parse error.


> I believe that there is already a wishlist entry or possibly upgraded to a todo entry to implement multiline quoting (sometimes called heredocs) where you can specify that the next several lines will the character string of interest (<<END
> ...
> END
> in Perl, some shell scripts, and probably others).  If this is implemented, then this would be one approach for the above (but still hard to visually parse if used on code and not clear documentation).
>   

i don't find particularly appealing the idea of using anything designed
for other purposes (e.g., functions, if(FALSE), brew, here docs, etc.)
to provide for block comments.  if you do think of having block
comments, do it with block comment syntax, not ugly hacking.

> The c-style of /* */ allows both types and you can comment out part of a line, but it is not simple to match and has its own restrictions.  Friedl in his regular expressions book takes 10 pages to develop a pattern to match these (and the final pattern is almost 2 full lines of text in the book).  And this is without allowing nesting.  If we don't allow nesting of comments, then in the future someone is going to comment out a block of code that is not working and they want to skip for now, but that block is going to already have a comment inside which will then screw up the parsing due to the no-nesting rule, then we will have a whole new discussion when that person posts to the list with a complaint that things are not working as expected.  Sticking with # to the end of the line is simple, and with modern editors, easy.
>   

with modern editors you can easily introduce getters/setters together
with members in java, and yet many modern languages provide features
that allow you to use metaprogramming and avoid editor-dependent
tricks.  besides, there are people who prefer to code with plain old
not-so-superduper editors.


> Consider the following code, what parts are commented out and which should be run?
>
> x <- rnorm(100)
> /* begin of code that does not work yet, I will come back to this later
> y <- rnorm( length(x), mean(x)
> txt <- " ************/
> z <- runif(20)
> /******"
> mean( (x+3)*10
>
> end comment */
> mean(x)
>
>   


consider the following code:

somefunction(x<-1)

will x be assigned to or not?

you can always give pro and counter examples, and i agree things should
be as complex as needed, but as simple as possible.  what you show above
is clearly a design issue.  once you decide on the design, it's just to
implement it accordingly.  in the above, either way is reasonable, in
principle. 

consider the following example:

foo <- "
# to comment or not to comment?
"

how many characters will foo have?  it's just the same sort of problem
-- would this be a reason to prohibit any sort of comments in r?  if
this is easy to parse correctly, what's wrong with the above?  it's
exactly the same issue -- locally switch off commenting when inside
string delimiters.

vQ