[R] How to comment in R

Wacek Kusnierczyk Waclaw.Marcin.Kusnierczyk at idi.ntnu.no
Wed Feb 11 23:48:57 CET 2009


Greg Snow wrote:
> Apparently I was not clear in my intention in my original reply.  I have no problem with you or anyone else implementing this in whatever way.  Someone could even use Friedl's regex to write a preprocessor in R, he did the hard work already if you follow the rules that he based his regex on.  I think the hard/non-trivial part is agreeing on the rules, and then dealing with all the future posters who expected a different set of rules.
>
>   

indeed;  the problem has been successfully solved, it's just to port it
from c to r, more or less, possibly with simplified syntax (e.g., no
nested blocks, block comments starting and ending only at the beginning
of the line, etc.)

(for those interested, friedl's example is in sec. 6.7 of mastering
regular expressions by o'reilly)

>
>> hey, be fair.  i was talking about the perl-style pod block comments,
>> where it *is* very easy to implement. 
>>     
>
> Your phrase that I responded to was:
> "an extension to the parser that would accept multiline start-end comment
> tags, be it c-style /* */, perl-style =pod =cut, whatever, should be
> fairly  trivial to implement."
>
>   

ok, got me, but implementing perl pod-style blockk comments is really
trivial, modulo open string literals.


> I interpreted the part after the last , to refer to the whole list, you apparently meant it to refer to only the last element of the list (English list, not R list).  I could show this to my friend that is a high school English teacher and see what he thinks, but I would prefer to just blame the English language (or the American corruption thereof) rather than each other.
>   

it's ok, i did say that, but i mean the above, and also that
implementing c-style (or pl/i-style, for that matter) is an
implementational exercise over a solved problem.


>  just any* line that starts with
>   
>> =[^\s] (including =cut; the pattern is perhaps just slightly more
>> complex, but it doesn't really matter here) in a non-block-comment
>> context starts a block comment, and only a line with =cut\s in a
>> block-comment context ends a block comment.  as clear as that.  #=head
>> does not start a block comment, and #foo =cut does not stop a block
>> comment.  is this really difficult to conceive,  agree on, and
>> implement?
>>     
>
> OK, implement your idea of #start and #end at the beginning of lines, probably easy to implement.
>
> Here is my prediction of what will happen when/if that is added.
>
> You will use it as intended only putting free text between the #start and #end tags so that it is clear that it is documentation/comments.
>
> But someone else upon learning of the existence of #start and #end will start using it to skip over sections of code that doesn't work, 

this would be what i'd do, rather than string-commenting.  for the
latter, it's enough (in most cases) to just write string literals with
no assignment.

> or that was redone a different way, etc.  Then they will eventually try to comment out a block with the comment already in it (nesting) or misread something because the line containing #start or #end will have scrolled off the screen, or will want to start/end the comment part way through a line.  When they discover the problems due to them wanting the #start #end construct to do more than you intended then they will post asking why they don't behave like /* */ in SAS/C/etc. and this whole discussion will start again.
>   

no;  i would just follow the rule and repetitively refer them to tfm,
provided it will have an appropriate entry.  btw., try ?'#' and
apropos('comment')


> Is that enough reason to not implement it. Probably not, but don't claim that you were not warned.
>   

it was not enough reason to not implement a number of annoying features
already there in r, and it is even less so to remove them.


> To get something added to the main R you need to convince someone that the benefits outweigh the costs.  My attempted point is that the costs include more than just the implementation, there is the documentation and dealing with all the people who don't read the documentation and expect it to behave differently.
>   

scare me more, please ;)

> I believe that there is a small benefit to what you propose, in my mind it does not outweigh the potential cost (but my opinion on this does not really matter, as I am not part of R-core and will have little or no impact on what is or is not added).  If others whose opinions on this do matter are not jumping on the bandwagon to implement this, then it is probably for the same reason, they are not convinced that the benefits outweigh the costs.  You can:
>
> 1: live with it (or without it)
> 2: convince them that the benefits are greater
> 3: convince them that the costs are less
>
>   

i'll live without it.  just adding my few cents to a discussion started
by a user or two asking, not for the first time, about block comments in
r.  as you said, it's probably already on the wish list, or the todo
list, but as duncan says, it's not needed.



>   
>> * not inside string delimiters, for example.  already solved in r for
>> single line comments-like multiline strings.
>>
>>
>>     
>>> While the parser can process the comments without using regular
>>>       
>> expressions, some of the issues that Friedl brings up still need to be
>> considered in deciding the rules.  Implementing this in the parser may
>> well be trivial once the rules are decided on (but way beyond me), but
>> I still think that deciding on the rules and documenting them is far
>> from trivial.
>>     
>> might be helpful to see some concrete counterexamples.
>>     
>
> I don't understand what you want as a counterexample.
>   

an example explaining why it would be far from trivial to decide on a
simple multiline comment scheme.
(if 'far from trivial' referred to documenting them within the r
help/manual system, maybe you're right, i don't know.)

> I think that the fact that nobody has committed either direction on Duncan's example supports my point.
>   

does it?  it's just a matter of very simple choice.  perhaps simpler and
less grave than that of making x[,1] drop dimensions by default or not.


>>> I have no problem with someone adding this capability to R, I just
>>>       
>> prefer that R-Core spends their time on higher priority items.  If
>> someone else wants to contribute the change, I won't complain (unless
>> it breaks my existing code, which is unlikely if done properly), I just
>> wanted anyone who was thinking of doing this to think about some of the
>> potential pitfalls so that if they implement it, they implement it
>> well.
>>     
>>>       
>> it's *design* that has to be done properly in the first place.
>>     
>
> That is what I was trying to say (along with the fact that the design may not be trivial).
>   

a fairly design-trivial block comment design has already been mentioned.

vQ




More information about the R-help mailing list