Front page | perl.perl5.porters |
Postings from April 2010
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'v noticed:
- 3-arg open() command not encouraged widely.
- Use of 'or' and 'and' not encouraged widely as a more safe and
readable over the '||' '&&' operators.
- Code indeantion and placement deviates from manual page to manual
page (there are 1, 2, 3 space etc. indentations)
- Keywords are treated like function calls:
if($this and $more) => if ($this)
while($that and $more) => while($that and $more)
- for-loops do not encourage the use of 'my' variable localizations:
for $var (...) => for my $var (...)
- Some conditionals could be written easier to the eye by reducing
function call parens. E.g
if (stat$($filename))
=>
if (stat $filename)
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;
- Chunks of code do not have breaks to see where a statement group
starts and where next continues. Like stucking "use", "my",
"while", "if" avery stemenent together above and below.
I've started fixing the the issues, but I would like ask:
- Would all of these be candidates for adjusting?
- Can I use perlstyle.pod as the guidelines for chnages?
- How should I prepare the chages 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,
Jari
Thread Next