Front page | perl.perl5.porters |
Postings from April 2010
Tom Christiansen <tchrist@perl.com> writes:
Let me tell you how I approach the documentation: With the eyes like how
a starter perl programmer would reads them. From this perspective I tend
to favor practices which:
- Are safer than average (in this case I refer to: 'and', 'or' ops)
- Improve readability, that is encourage use of whitespace where
applicaple. Both vertical and horizontal between tokens.
- Are typiacl to Perl. Like omitting function call parens
in simple contexts: "if (stat $filename)", "for (sort keys %hash)"
>> - 3-arg open() command not encouraged widely.
>
> There are several reasons for that, some good and some less so.
> The trick is to know the difference.
Please let me know in which cases there should not be used 3-arg open
and I'll adjust accordingly.
>> - Use of 'or' and 'and' not encouraged widely as a more safe and
>> readable over the '||' '&&' operators.
>
> That's because they aren't. This is a myth.
I can't see how that would be a myth. Even ISO C++ finally got those for
better readability.
The "&&" and "||" increase signal to noise ratio in lines and require
extra parens for each sides to protect from tight binding.
>> - Code indentation and placement deviates from manual page to manual
>> page (there are 1, 2, 3 space etc. indentations)
>
> I noticed this on my last past through perlfunc, and wasn't sure how it
> came about. Probably by accident, I suppose. I'd rather see them as 4,
> but it may be that you run into problems with your horizontal line lenght
> on nroffed manpages.
>
>> - Keywords are treated like function calls:
>
>> if($this and $more) => if ($this and $more)
>> while($that and $more) => while ($that and $more)
A typo fixed to the right hand examples
>> - for-loops do not encourage the use of 'my' variable localizations:
>
>> for $var (...) => for my $var (...)
>
> Sometimes it gets too busy for the important point to come through.
> This note suffices:
>
> Note: here and in subsequent examples, good style (and the C<use
> strict> pragma) would dictate that you add a C<my> modifier to
> declare a new lexically scoped variable, like this:
>
> my $diff = abs($first - $second);
>
> However, we've omitted C<my> from most of our examples for clarity.
> Just assume that any such variable was declared earlier.
An average reader does it like this:
He is busy. The deadline is at hand. He looks at the documentation
and has no time to look up, down and all over to see notes like:
"we've omitted C<my> from most of our examples".
He locates the needed place in the documentation, scrolls to the
right spot, he wants the answers, and gets by with his code. Never
to look back, until next problem is at hand.
Therefore it would be very good if the documentation always showed the
best practices in all places, with no compromises.
In none of the code I went through in e.g. perlfunc.pod introduced any
excessive clutter when "my" was injected into the for-loops.
>> $var = function(arg, arg)
>
>> =>
>
>> $var = function arg, arg; # An example: $str = sprintf "%02d", 1;
>
> That's a slippery slope.
One of the great Perl's power comes from this. It reduces the extra
punctuations and at the same time "frees" the programmer to see the code
differently as he used to.
When a traditionally educated programmer (C, Java, <pick language>),
first time sees that parens can be omitted, he is shocked. He insists on
using them as "the one true function call convention".
But really, it is relaxing to see:
my @array = sort keys { $a <=> $b} %hash
my $var = oct $value;
my $str = sprintf "%04d-02d-02d", $yyyy, $mm, $dd;
That's what "getting into Perl", I believe, is all about.
>> - Chunks of code do not have breaks to see where a statement group
>> starts and where next continues. Like stucking "use", "my",
>> "while", "if" every statement together above and below.
>
> I don't know what that means. You mean not enough vertical whitespace
> for grouping code chunks?
Close. More vertical spaces to spearate groups, like "while", "if" etc.
An example from pod/perlipc.pod
pipe(READER, WRITER);
$pid = fork();
defined $pid or die "fork failed; $!";
if ($pid) {
close READER;
if (my $sub_pid = fork()) {
close WRITER;
}
else {
# write to WRITER...
exit;
}
# write to WRITER...
}
=>
pipe(READER, WRITER);
$pid = fork();
defined $pid or die "fork failed; $!";
if ($pid) {
close READER;
if (my $sub_pid = fork()) {
close WRITER;
}
else {
# write to WRITER...
exit;
}
# write to WRITER...
}
>> - Can I use perlstyle.pod as the guidelines for changes?
>
> Depends on who hacked it last.
How to proceeed then?
Thanks,
Jari
Thread Previous
|
Thread Next