A. Sinan Unur replied:
I think you are cheating a little here. Your actual stated
opinion seems to me that everything that you might ever
want to reference should be included in the standard Perl
documentation.
The intent of this thread's original post was that I wanted to know
of all the perldocs that referenced or explained Schwartzian
Transforms. (The fact that they were not readily found made me wonder
if I was searching on the wrong keyword.) But the fact that I want to
read all the explanations of Schwartzian Transforms that exist in the
standard perldocs doesn't mean I'm not interested in non-perldoc
explanations. (It's just that I wanted to be aware of all the perldoc
ones -- and that the one I did find in perlfaq4 took a while to find.)
As for referencing the standard Perl documentation over other
things, I happen to think that, although the perldocs aren't perfect
(and what is, really?), I think they are *very* good sources of
information. So good, in fact, that I encourage all Perl programmers
(beginner and advanced) to use them often, even with small Perl
questions (and occasionally with some C questions, believe it or not).
No one can argue with the proposition that when you
do something clever, you should put something that
explains where that came from.
I really wish that were true (that is, that no one can argue with
it), but I've had plenty arguments about it. I'll find code that
definitely looks like a bug, but it turns out that this is for a
special case, which of course isn't documented. When I alert the
original coder about it, he tells me how any idiot can look at the code
to see what it's doing (despite the fact that it would require looking
at a half-a-dozen functions scattered across several files) and resents
any effort to encourage commenting the intent of that code.
The big problem is that the coder himself is no moron. In fact, I
find that very often these types of coders are quite intelligent -- so
much so that they are unaware of how confusing their code looks to
"less intelligent" people like myself (or any other person who didn't
experience the coder's same thoughts that led to the final code).
Often their response for clarification will be to read the code
yourself which, I'll admit, works sometimes, but won't help if you
think you understand (but really don't) or if there is a bug that crept
in due to a maintainer misunderstanding the code. In cases where bugs
ARE lurking around, it's difficult to see which part of the code is the
correct piece and which part is the bug. Because there are no
accompanying comments, I don't know what the original coder intended
the correct code to be.
One of my favorite Perl quotes is this one from p. 129 (in chapter
10) of "Learning Perl" (3rd edition) by Randal L. Schwartz & Tom
Phonix:
"It's important to remember that you're always writing
code for two readers: the computer that will run the
code and the human being who has to keep the code working.
If the human can't understand what you've written, pretty
soon the computer won't be doing the right thing either."
Of course, it's not always clear at what point code becomes "clear
enough." Expert Perl programmers will no doubt understand more
decently-written Perl code than those just beginning to learn Perl. So
to be on the safe side, I always encourage people to write their
comments in such a way so that a maintainer "not quite as intelligent
as you" can understand it.
I really don't understand you, I am afraid. Do you propose that what
gets included in the standard Perl distribution should depend on what
programmers put in their comments?
No. What I meant was closer to the opposite statement: what gets
included in programmers' comments should depend on what is included (or
rather, what isn't included) in the standard Perl distribution (or
readily available documentation).
So, in the case of Schwartzian transform, it should be fine
to reference Randal's original article, and move on, instead
of insisting that Schwartzian transform should be explained
in the standard Perl documentation.
Yes, provided that Randal's original article is readily available to
the maintainer. Like I said, I really like perldocs, and one of their
strengths is that they will always be available, even when certain key
sites go down. But any referencing of a technique that 50% or more of
maintainers won't be familiar with is a good practice. And I don't see
the harm in referencing a website provided that it is reasonable to
assume that it will always be available to the maintainer when he/she
needs it.
You seem to want to go off on tangents about dimwit
programmers who cannot figure out File::Find, or
map in void context, or comments.
Ah, but that's part of my point (and excuse my tangent): the person
who made that mistake with File::Find was no dimwit. He was a rather
intelligent programmer who was just new to Perl. He made that mistake
because he was still somewhat disoriented to the world of Perl.
I remember when I was new to Perl and I wanted a function that was
similar to glob() but worked recursively. From "Learning Perl" I knew
to use the File::Find module, but when I read its perldoc, I was very
confused. The reason? I was disoriented due to the fact that I was
expecting to find a function that could be used like:
my @listOfFiles = recursiveFind($topLevelDir);
but instead found File::Find::find() which worked in a way that was
very unfamiliar to me. (And I'm not saying that File::Find::find() is
a bad function (after all, it is a lot more flexible that the
hypothetical recursiveFind() function), but I am saying that it's not
what people unfamiliar with recursive file finding in Perl are
expecting to find. Therefore, they might not even realize that it's
recursive, which was how the programmer I mentioned earlier made that
particular mistake with File::Find. It's not that he was a "dimwit";
it's just that I forgot my own confusion that I experienced when I
first read about it, and never even considered that future maintainers
might experience the same confusion that I initially had with
File::Find. I assumed that since I knew how to use it everybody else
should, especially if they're smart enough to read "perldoc
File::Find".)
The issues you raise are all valid,
but irrelevant to the question I asked.
For the record, that question was:
"Does the explanation of the "Schwartzian Transform"
-- a general algorithm -- need to be included with Perl?"
Sorry -- as you probably already noticed, I sometimes go off on
tangents. But back to your question... and here's your answer:
I'm not sure if it "needs" to be included in the standard perldocs,
but it sure would be nice to have.
One final thing: The standard perldocs are authoritative: if the
perldocs condone something, decent Perl programmers will be more likely
to study it and make an effort to understand it. And if the
Schwartzian Transform is included, decent programmers will less likely
dismiss it as if it were just another hard-to-understand piece of
"hack" code.
Aaaanyway, I am probably becoming too pedantic, so I'll stop now.
Yeah... I'm guilty of that, too.
Take care,
-- Jean-Luc
