[R] How to comment in R

[Wacek Kusnierczyk]

Duncan Murdoch wrote:
> On 2/11/2009 2:27 PM, Wacek Kusnierczyk wrote:
>> Duncan Murdoch wrote:
>>> On 2/11/2009 1:21 PM, Stavros Macrakis wrote:
>>>> On Wed, Feb 11, 2009 at 12:32 PM, Greg Snow <Greg.Snow at imail.org>
>>>> wrote:
>>>>> ...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....
>>>>
>>>> Though there is a real debate about the value of multiline, possibly
>>>> nested, comments, the regular expression argument is a red herring.
>>>> Lexical analysis of multiline comments is a solved problem (and not a
>>>> particularly difficult one!), and matters only to language and editor
>>>> implementors.  Emacs handles them with no problem.
>>>
>>> I agree about that.  I think the lack of multiline comments comes from
>>> design considerations rather than implementation ones.   They're just
>>> not needed, and having two types of comments would lead to weird
>>> interactions, e.g. is the block comment closed in the lines below?
>>>
>>>   /*
>>> #  */
>>
>> it's still a simple design decision which, once made, can be implemented
>> coherently.
>
> I agree it's a design decision and once made implementation would be
> easy, but I don't agree that it's a simple design decision.  If it
> was, you'd be able to tell me the obvious answer to my question.  If
> the answer isn't obvious, then it's a source of errors in programs
> when people assume the wrong behaviour.

these are things you shouldn't be willing to say.  is it *obvious* that
x[,1] should return a vector not a data frame or matrix (depending on
what x is)?  how *obvious* it is?  how *obvious* will it be to a user
who has little experience with r and will make best guesses?  how
*obvious* will it be to a user who comes from matlab or the like?

i can tell you the obvious answer to your question:  if tfm said that a
# being the first non-whitespace character in a line appearing in an
open comment block does not work as a single line comment tag, then the
block comment above is closed.  if tfm said otherwise, it would not be
closed.

again and again, one message pervasive on this list is:  if you don't
know, if something is not obvious*, rtfm carefully.  here's your
answer:  decide how to treat overlapping mulitline and single-line
comments, put into a man page, and you're done.  just like with x[,1]. 
and it doesn't really have to be obvious or intuitive -- just like with
x[,1].

* i'd add:  the more something is obvious, the more you're advised to rtfm.


>
> In another message, you pointed out the ugly construct
>
> x <- "
> # not a comment
> "
>
> which arises because R allows multi-line string literals, and also
> gives priority to string content over # comments.  This is a bad
> design, in my opinion.  (There shouldn't be multi-line string literals.) 

it's a design choice which can be considered bad or good, depending on
the point of view.  you're sort of saying things you should not be
willing to say, again.  when i criticized r, with concrete examples, for
the design being bad because of *incoherence*, i was promptly accused of
being dogmatic, and the issues were explained away as design
'features'.  now you're saying 'bad design' -- well, it's just a choice,
not even leading to any incoherence, why would it have to be bad?  i
find it more convenient and readable to write

x =
"foo
bar
dee"

rather than

x = "foo\nbar\ndee"


in perl you can write multiline string literals, whereby you include the
newlines in the string, as in r.  whcih is sort of redundant, since perl
supports here documents.  in python you can enter a string literal on
multiple lines escaping the newlines, but the newlines do not belong in
the string.  which is good design, which is bad? 

btw. if you strike the tab key while writing a string literal in an r
script, you get a tab character inside the string.  is this bad design,
too?  how different are tabs from newlines?  from spaces?


> You probably haven't studied Rd syntax as closely as I have lately, 

fortunately, haven't at all.

> but in an Rd file, # comments are treated as R treats them (i.e.
> within a string they don't do anything), % comments are always in
> effect.  You should see how many people get confused by the handling
> of % comments in Rd files.  But that's not something we can change: 
> there are something like 100000 Rd files on CRAN.

i can believe, it's pretty enough for me to see how many people get
repeatedly confused by many other features in r.



>
> So if the behaviour isn't very obvious in cases like the one quoted
> above, and if the new syntax doesn't add any new expressiveness, I
> would be opposed to adding it.

what about cases where the syntax is 'obvious' and yet r does the
opposite of what one would expect?

vQ