Hello list, Is there any way to perform a block comment in R? In C++, anything in between a /* and */ is considered a comment, and it allows programmers to comment out chunks of code for testing and debugging. Is there such a feature in R? Cheers, Wee-Jin
Wee-Jin Goh wrote:> Hello list, > > Is there any way to perform a block comment in R? In C++, anything in > between a /* and */ is considered a comment, and it allows > programmers to comment out chunks of code for testing and debugging. > Is there such a feature in R?This has frequently been asked on the list. Try to google for it. You will find answers like if(FALSE){" code block commented "} or "use a good editor that supports commenting and uncommenting blocks". Uwe Ligges> Cheers, > Wee-Jin > > ______________________________________________ > 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.
+1 for Python style comments.
"""
your comments here
and some more
...
and some related info
"""
jab
--
John Bollinger, CFA, CMT
www.BollingerBands.com
If you advance far enough, you arrive at the beginning.
Please let's not waste any time trying to figure out how to add block comments to R. In any guise they are highly error prone. Although its precursors (PL/I and Pascal) had block comments and did not have end-of-line comments, the programming language Ada was explicitly designed to have end-of-line comments and not block comments, as block comments were thought too easy to write incorrectly and too easy to misread. As just one example, the version of vim I have does syntax highlighting, BUT "Vim doesn't parse the whole file", so if you have code in the middle of a block comment it may be highlighed incorrectly. Commenting code out and providing documentation comments are easily done with a good editor, although R documentation comments really belong in files where help() can find them. In the text editor I use, comment-region (using end-of-line comments) and uncomment-region (ditto) are just two keystrokes each; it's LESS effort than writing block comment delimiters would be. Also, when writing a big comment, the newline key automatically copies <white space>*(<end of line comment mark> <white space>*)? to the beginning of a new line, so again it is less typing to make a block comment using end-of-line comments than /* ... */ or anything like that, and of course fill-paragraph and justify-paragraph (two keystrokes each) can cope with the comment marks (a change from lines with comment marks to ones without, or vice versa, constitutes a paragraph break).
Note that if you only have block comments in a language, its much harder to do this: http://www.xkcd.com/c156.html Barry
And of course in emacs you can select the region to comment then hit
Ctrl-x r t and type #: all the lines in that region will have a # at the
beginnig
To uncomment Ctrl-x r d
Stefano
On Fri, Oct 06, 2006 at 07:05:52PM -0400, Jim Lemon wrote:
<Jim>And of course for NEdit, all one needs to do is select:
<Jim>
<Jim>Preferences | Default Settings | Customize menus | Macro Menu
<Jim>
<Jim>Then select the "New" option at the top of the menu list,
<Jim>
<Jim>Give it a name (I call this r_comment),
<Jim>
<Jim>Enter the following code:
<Jim>
<Jim>replace_in_selection("^","#","regex")
<Jim>
<Jim>click on "Apply" and then "OK"
<Jim>
<Jim>You will have an item named "r_comment" on your macro menu
<Jim>
<Jim>Simply select the area you wish to comment out and run the macro.
<Jim>
<Jim>To remove comments, you can program another macro (r_nocomment)
<Jim>
<Jim>replace_in_selection("#","")
<Jim>
<Jim>You can give both of these a keystroke invocation if you wish.
<Jim>
<Jim>Happy commenting!
<Jim>
<Jim>Jim
<Jim>
<Jim>______________________________________________
<Jim>R-help a stat.math.ethz.ch mailing list
<Jim>https://stat.ethz.ch/mailman/listinfo/r-help
<Jim>PLEASE do read the posting guide
http://www.R-project.org/posting-guide.html
<Jim>and provide commented, minimal, self-contained, reproducible code.
Hi all,
Indeed, block comment is more clean and elegant than line by line.
If the R interpreter will recognizes it (I'm not sure if already
recognizes), we
will spend no more than few hours to make the syntax of the main editors
compatible, isn't it?
Regards,
--
Jose Claudio Faria
Brasil/Bahia/Ilheus/UESC/DCET
Estat?stica Experimental/Prof. Adjunto
mails: joseclaudio.faria em terra.com.br
jc_faria em uesc.br
jc_faria em uol.com.br
tel: 73-3634.2779
And of course for NEdit, all one needs to do is select:
Preferences | Default Settings | Customize menus | Macro Menu
Then select the "New" option at the top of the menu list,
Give it a name (I call this r_comment),
Enter the following code:
replace_in_selection("^","#","regex")
click on "Apply" and then "OK"
You will have an item named "r_comment" on your macro menu
Simply select the area you wish to comment out and run the macro.
To remove comments, you can program another macro (r_nocomment)
replace_in_selection("#","")
You can give both of these a keystroke invocation if you wish.
Happy commenting!
Jim
I wrote:
R documentation comments really belong
in [.Rd] files where help() can find them.
Barry Rowlingson <B.Rowlingson at lancaster.ac.uk> replied:
R documentation comments belong in .Rd files at the moment, but how
joyous would it be if they could be included in the .R files?
How joyous? About as joyous as a root canal job without anaesthetic.
I used to be a fan of including thorough documentation in code.
Then JavaDoc hit the world, and many of the languages I use are following
suit with their own EDoc or PlDoc or whateverDoc mess.
I have read far more Java than I ever wanted to, and the more Java I read
the more I *hate* JavaDoc, and the more I am convinced that if you want
to mix documentation and code you need *really* sophisticated tools (like
Web in its various incarnations) or really simple tools (like Haskell's
"Bird Tracks", a notation I have adapted to my own use for several
other
languages).
.Rd files are semisophisticated; if JavaDoc is a reliable guide, then
shoving that stuff into .R files would be horrible.
Do I need to point out the single biggest difference between JavaDoc
and .Rd? Maybe I do. .Rd files are *USEFUL*. (Because of references,
examples, consistency checking, &c, and because they can describe closely
related GROUPS of functions rather than being nailed to specific methods.
The right documentation about the right topics at the right level of
detail.) JavaDoc-style documentation seems to systematically encourage
bulky documentation of low utility.
Okay, this is all part of my incessant whining to make R more like
Python, but I've found managing separate .Rd and .R files a pain. If .R
files could have embedded documentation you'd have one source for code,
documentation, tests etc. I did play about with this in the Splus days,
attaching documentation strings to functions with attributes, but it was
just kludgy without a proper mechanism.
Let me point out that right now there is NOTHING stopping anyone mixing
.Rd and .R and test cases as they wish. How? Here's how:
$poomat.1
.TH POOMAT 1 "Oct 2006" "Version 1.0" "USER
COMMANDS"
.SH NAME
poomat - poor man's Tangle
.SH SYNOPSIS
.B poomat
file ...
.SH DESCRIPTION
.B poomat
extracts several interleaved files (such as documentation,
source code, and test cases) from a single file. You can
pack several files together using shell archives, tar files,
or ZIP files, but those are distribution formats, not meant
to be edited as single files.
.B poomat
lets you scatter a file in pieces, interleaved with other
pieces, so that a function, the documentation for the function,
and the test cases for the function can all be in one place.
.SH OPTIONS
None.
.B poomat
concatenates its input files just like
.IR cat (1)
or
.IR awk (1)
and writes to files named in the input.
.SH INPUT LANGUAGE
The input to
.B poomat
is a sequence of chunks. Each chunk is introduced by a line
consisting of a dollar sign in column 1, immediately followed
by a file name. The first chunk for any file name creates a
new file; remaining chunks for the same file are appended to it.
.SH BUGS
Unlike
.IR tangle (1),
.IR ctangle (1),
and other Literate Programming tools, there is no facility for
re-ordering chunks. Nor is there any macro facility.
.PP
It is up to you to make sure that the file names are portable.
Stick to 8.3 file names without any directory affixes and you
should be right.
$INSTALL
Edit the first line of the poomat file to refer to the right
version of awk (nawk, gawk, mawk) for your system, and then
move the poomat file to some directory in your $PATH.
$poomat
#!/usr/ucb/nawk -f
BEGIN { output = "/dev/stdout" }
/^[$]/ { output = substr($0, 2); next }
{ print >output }
Yes, I do mean the whole thing is a three-line AWK script.
Yes, I do mean it is language-independent, and doesn't NEED to be built
into R or anything else.
Yes, I do mean that the source code, documentation, and test cases get
separated as part of the build process. So?
For people interested in doing stuff like that with C or C++, it really
doesn't take a lot of work to make poomat notice a
/[.][chCH][pxPX+]?[pxPX+]?$/ suffix and emit a #line directive.
OK, here it is:
/^[$]/ {
output = substr($0, 2)
if (/[.][chCH][pxPX+]?[pxPX+]?$/)
print "#line", FNR+1, "\"" FILENAME
"\"" >output
next
}
So your C or C++ debugger can refer back to the original file.
Maybe that should be in the official version, but R doesn't need it.
I must say I agree with Richard O'Keefe who wrote:> I wrote: > R documentation comments really belong > in [.Rd] files where help() can find them. > > Barry Rowlingson <B.Rowlingson at lancaster.ac.uk> replied: > R documentation comments belong in .Rd files at the moment, but how > joyous would it be if they could be included in the .R files? > > How joyous? About as joyous as a root canal job without anaesthetic.<etc.> <snip> (a) I don't speak Python and I don't believe I ever will; I'm not sure what Python does; I don't want to know. R does what I want to do. I don't want to have to learn Python syntax to do something with which I am very happy doing the R way currently. (b) Modularity is a ***Good Thing***. Code should be code, documentation should be documentation. They should click together but be kept separate. (c) The R documentation system is neat, efficient, well thought out, and well constructed. It is an intrinsic part of the nature of R. (It's one of the --- many --- reasons I like R better than Splus, which I no longer use.) Changing the R documentation system to something (Monty?) Pythonesque would change the nature of R and make it uglier. cheers, Rolf
Apparently misunderstanding the argument,
BBands <bbands at gmail.com> wrote:
Should R be editor specific? Or should it be editor neutral?
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.
In my view blocks comments are a desirable, editor-neutral approach.
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.
Note that most of the more recent languages have some form of block
comment capability.
http://en.wikipedia.org/wiki/Comment#Summary
That list is not a list of "more recent languages"; it is a list
containing
both old languages and new ones. Some of the entries (such as the one for
Algol 60), are clearly wrong. (In fact the Algol one is doubly wrong,
because the language always was Algol, not ALGOL.) So is the Scheme entry
wrong: there are no block comments in any official version of Scheme and
never have been. The list is missing Burroughs Algol (% end of line
comments), Prolog (%...\n and /*...*/), Pop-2 (!...! or !...\n), and many
others. If you want to be pedantic, the list is technically wrong about
C and C++. We also find COBOL, with some interesting variants, missing.
Texinfo is another one that's wrong. Quite a lot of entries are wrong.
If "more recent languages" just means languages that are still in use,
it's a pity APL isn't there; the APL "lamp" character
(comments are supposed
to be illuminating, no?) U+235D is cute.
We find
- languages which have copied PL/I (/* ... */)
- languages which have copied BCPL (//)
- languages which have copied Pascal (* ... *)
- languages which have copied sh (#)
- languages which have copied Burroughs Algol (%)
- Fortran (only ever end-of-line comments, first C and now !)
- BASIC (only end-of-line ' and REM comments, and you would certainly
have to call VB.net "recent")
- eclectic languages
- languages designed for high reliability, notably Ada and Eiffel (--)
Basically, most language designers have pretty much blindly followed
designs from the 1960s, with the notable exception of Ada and Eiffel.
The Haskell experience is instructive. The Haskell designers thought they
could put in nesting block comments {-...-} and make them work. But it
took several iterations of fiddling with the details, and they *still*
don't work in every case.
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.
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.