[R] R programming style

[Terry Therneau]

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