[R] R programming style

[hadley wickham]

On Feb 12, 2008 9:07 AM, Terry Therneau <therneau at mayo.edu> wrote:
> 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.

See http://steve-yegge.blogspot.com/2008/02/portrait-of-n00b.html for
a fairly well reasoned discussion of some of these issues.

Hadley

-- 
http://had.co.nz/