Front page | perl.perl5.porters |
Postings from April 2010
In-Reply-To: Message from Jari Aalto <jari.aalto@cante.net>
of "Fri, 02 Apr 2010 19:55:10 +0300."
<87mxxl7q1d.fsf@jondo.cante.net>
> I noticed that many of the manual pages are inconsistent with the
> perlstyle.pod guidelines. While this may seem like a minor quibble, I
> personally think the quality of documentation is visible from the
> writing and adhering to the style conventions.
> Some issues that I've noticed:
> - 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.
> - 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.
> - 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)
> while($that and $more) => while($that and $more)
if ($this && $more)
while ($that && $more)
> - 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.
> - Some conditionals could be written easier to the eye by reducing
> function call parens. E.g
> if (stat$($filename))
Spurious $.
> =>
> if (stat $filename)
Perhaps.
> Likewise for the variable assignments and simple built-in perl
> function calls:
> $var = function(arg, arg)
> =>
> $var = function arg, arg; # An example: $str = sprintf "%02d", 1;
That's a slippery slope.
> - 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?
> I've started fixing the the issues, but I would like ask:
> - Would all of these be candidates for adjusting?
No.
> - Can I use perlstyle.pod as the guidelines for changes?
Depends on who hacked it last.
> - How should I prepare the changes for inclusion?
> I've worked through GIT blead repository and have all the patches in
> standard format for:
> git am *.patch
> I could send the patches for each pages in a separate threads?
> Let me know how could I be of help to improve the documentation,
Any help is better than no help: it should be encouraged and thanked.
Thank you,
--tom
Thread Previous
|
Thread Next