Front page | perl.perl5.porters |
Postings from April 2010
Re: RFC: Perl manual pages -- update to follow the perlstyle.podguidelines
Thread Previous
|
Thread Next
From:
H.Merijn Brand
Date:
April 2, 2010 12:58
Subject:
Re: RFC: Perl manual pages -- update to follow the perlstyle.podguidelines
Message ID:
20100402215745.47811c2e@pc09.procura.nl
On Fri, 02 Apr 2010 21:30:56 +0300, Jari Aalto <jari.aalto@cante.net>
wrote:
> 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)
As Tom said, and and or are no safer than && and ||, they just have a
different precedence. The `safer' part is when parens are left out
open (FOO, "foo.txt") || die $!; OK
open FOO, "foo.txt" || die $!; Wrong
open (FOO, "foo.txt") or die $!; OK
open FOO, "foo.txt" or die $!; OK
The precedence is also helpful to leave out parens in more complicated
expressions, but I don't think perl style guides should be promoting
that
return if ($a && $b) || ($c && $d);
=
return if $a && $b or $b && $c;
better? not sure. Esp when I deparse I get confused:
$ perl -MO=Deparse -e'return if $a&&$b or $c&&$d;'
return if $a and $b or $c and $d;
-e syntax OK
Personally I prefer to use 'and' and 'or' to separate expressions from
actions:
expression and action;
$a eq "yes" or return;
use parens where it makes things easier to read, even if they are not
required.
> - Improve readability, that is encourage use of whitespace where
> applicaple. Both vertical and horizontal between tokens.
As said, whitespace doesn't always make things easier to read.
Sometimes it makes things harder to read.
$a {key} -> [1] -> {
key2 }-> ( "arg"
);
legal, a whole lot of whitespace, but clear? Absolutely not.
> - 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.
See at top
> 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.
Parens are not bad at all. They force the eye to group things that are
to be grouped. They take away ambiguity.
> >> - 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:
do they? not for me. Probably the eye of the beholder.
> >> 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:
No, the average coder hitting a deadline is probably more likely to
steal (read cut-n-paste) code from something that works (regardless the
style) than to read the docs. I know. I see that on a daily basis. And
the bad thing is that the pasted code is not even corrected to fit in
the current style, so inconsistency creeps in. Not even indenting is
corrected to make it fit in the block it is executed in.
> "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.
There is more than one way to do it. Coding is art. I don't think perl
coding style should be strict. Even PBP tell you that the main reason
to read the book is to THINK about the decisions you make in your team
regarding code style, layout and interface design.
> 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.
Here you use it yourself: FREEDOM!
> 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.
:) (/me agrees)
> >> - 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
The docs are about explaining the matter, not to make it longer with
unnecessary vertical whitespace. Please don't.
> 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?
1. Don't try to do all what you suggest at once.
2. Discuss each and every step before you propose a patch.
3. Accept the decision of the group
4. Wait till 5.12 is out :)
> Thanks,
> Jari
--
H.Merijn Brand http://tux.nl Perl Monger http://amsterdam.pm.org/
using & porting perl 5.6.2, 5.8.x, 5.10.x, 5.11.x on HP-UX 10.20, 11.00,
11.11, 11.23, and 11.31, OpenSuSE 10.3, 11.0, and 11.1, AIX 5.2 and 5.3.
http://mirrors.develooper.com/hpux/ http://www.test-smoke.org/
http://qa.perl.org http://www.goldmark.org/jeff/stupid-disclaimers/
Thread Previous
|
Thread Next