[R] R programming style
Terry Therneau
therneau at mayo.edu
Tue Feb 12 16:07:47 CET 2008
David Scott asked
"Views on Bengtsson's ideas would interest me as well."
I have only one serious disagreement with their suggestions
"6.3.2 In general, the use of comments should be minimized by making the code
self-documenting by appropriate name choices and an explicit logical structure".
The phrase "self-documenting code" is the description of a popular illusion.
Variable names that are obvious today will not be so when you look at the same
code 3 years from now, whether you make them long, short, or in between. I find
that each time I fix a reported bug in the survival code, I end up adding both
the fix and 3-4 new blocks of comments. These mostly represent features that
were "obvious" when I wrote the code; but I have just spent 20-40 minutes
reconstructing my understanding of the feature. ("I see what the code is doing,
but why on earth did I want to do that?")
Every comment, no matter how obvious, will be appreciated by future readers
of your code. And that includes yourself.
Minor disagreements:
1. They recommend an indent if 2 spaces, I much prefer 4. Perhaps its older
eyes, but I have trouble seeing the structure of larger blocks when the offset
is so small.
2. I do not like mixed case for function names. As a user, I now have to
remember not just the name of the function, but the pattern of capitalization
(often idiosyncratic) that the author chose to use. Within a function I have no
complaint; anything that improves readability is a good thing.
Agreements: 98% of what they say.
Terry Therneau
More information about the R-help
mailing list