Re: [R] R programming style

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

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/

______________________________________________
R-help_at_r-project.org 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.
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 https://stat.ethz.ch/mailman/listinfo/r-help. Please read the posting guide before posting to the list.

list of date sections of archive