On Feb 12, 2008 9:07 AM, Terry Therneau <[EMAIL PROTECTED]> 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@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.
