Re: [R] R programming style

From: hadley wickham <>
Date: Tue, 12 Feb 2008 11:28:16 -0600

On Feb 12, 2008 9:07 AM, Terry Therneau <> 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 for a fairly well reasoned discussion of some of these issues.



______________________________________________ mailing list
PLEASE do read the posting guide
and provide commented, minimal, self-contained, reproducible code.
Received on Tue 12 Feb 2008 - 17:31:55 GMT

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.2.0, at Tue 12 Feb 2008 - 18:30:14 GMT.

Mailing list information is available at Please read the posting guide before posting to the list.

list of date sections of archive