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
______________________________________________
[email protected] 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.
