If you recal, a short while ago I put a call out for an editorial
overhaul of the Perl Standard Documentation. To which, no one replied
saying they were fine. I also mentioned http://perl.clueball.com/ and
no one complained about the bullet points there. I can only assume
that meant agreement.
Putting my time and energy behind the call, I chose the 'Code examples
should follow the Perl sytle guide' bullet point. So, I read
perlstyle.pod and began updating doucmentation. I am fully aware that
my own style may have slipped into the process. I feel that my style
is a generally acceptable one that everyone can understand. In that
light, I don't think it's a bad thing if I make some minor changes
(single versus double quotes) in the process of making a whole
document better.
At the very top of perlstyle is says this:
The most important thing is to run your programs under the -w flag
at all times. You may turn it off explicitly for particular portions
of code via the use warnings pragma or the $^W variable if you
must. You should also always run under use strict or know the reason
why not. The use sigtrap and even use diagnostics pragmas may also
prove useful.
I know that documentation examples are not full programs. I still
think they should adhere to the above paragraph as much as possible.
I'm trying to do this in a way that does not detract from the overall
goal of the example.
For example (not one in the docs, but similar):
foreach $x ( 1 .. 20 ) {
foreach $y ( 1 .. $x ) {
print $x, ' ', $y, "\n";
}
}
Would be written by any one of us as something like:
foreach my $x ( 1 .. 20 ) {
foreach my $y ( 1 .. $x ) {
print "$x $y\n";
}
}
I don't think that detracts from the goal of the example. I do,
however, think it helps beginners overcome that 'use strict' hump, if
not, in due time, eliminate it.
Now sure, I like a 2 column indent where Larry requests a 4 column
indent. I consider that sort of requirement much less important and,
if a document was already generally consistent with something like
that, I adhere to the standards they used. My style will creap in,
but I feel my style is easy to read for a wide range of audiences, in
particular, beginners.
So, that's really why I'm doing this.
Casey West
--
Shooting yourself in the foot with APL
You hear a gunshot and there's a hole in your foot, but you don't
remember enough linear algebra to understand what happened.
