Front page | perl.perl5.porters |
Postings from February 2011
Re: perldoc improvements for map
Thread Previous
|
Thread Next
From:
Shlomi Fish
Date:
February 13, 2011 02:25
Subject:
Re: perldoc improvements for map
Message ID:
201102131225.24976.shlomif@iglu.org.il
Hi all,
On Saturday 12 Feb 2011 23:33:57 Abigail wrote:
> On Sat, Feb 12, 2011 at 10:58:17PM +0200, Shlomi Fish wrote:
> > On Friday 11 Feb 2011 16:44:27 Alexander Hartmaier wrote:
> > > I've tried to improve the docs for the map function with some help by
> > > castaway and the people on #catalyst because there was not a single
> > > example that uses block syntax and assignment to an array.
> > >
> > > Best regards, Alex
> >
> > Hi,
> >
> > I like the direction of the patch and as a general rule it seems nice.
> > Using my instead of package-scope variables and converting
> > << map $expr,@list >> to << map { BLOCK } @list >> is welcome and
> > recommended. It's a step in the right direction
> >
> > My reservations from it:
> >
> > 1. You should still show the map $expr, @list somewhere because people
> > may encounter it in the wild and we should document it. It should have a
> > comment as "not recommended" and with an explanation.
>
> Please, let's try to avoid "not recommended" as much as possible. I'm
> already spending way too much time fighting people who object to code
> because someone recommends against it, and it's not only taken as gospel,
> but as a weapon. PBP has already done way too much damage; unless there
> are very good reasons to do so, I think the "official" documentation
> should be very selective in recommending one style over the other.
>
> Personally, I never use "map EXPR, LIST", but that's a personal choice.
> If there are *objective* reasons to use one style over the other; state
> them, and let the reader draw his own conclusions.
>
OK, I'm sorry for starting a "colour of the bikeshed" discussion, which for
those who don't know what it is yet is:
* http://bikeshed.com/
* http://en.wikipedia.org/wiki/Parkinson%27s_Law_of_Triviality
And in regards to the more Perly context:
* http://www.modernperlbooks.com/mt/2009/10/from-novice-to-adept-on-answers-
to-smart-questions.html
(Short and non-broken URL - http://xrl.us/bihbcf ).
There are some technical reasons for prefering this way over the other and the
opposite, but both versions will be accepted by the compiler and I don't think
either one is going to be removed anytime soon. But this argument is still
about minutae.
So I'll just shut up.
> PBP has already done way too much damage; unless there
> are very good reasons to do so, I think the "official" documentation
> should be very selective in recommending one style over the other
Well, while some people have been influenced too much by what Damian said in
PBP, I think the post-PBP Perl world is still in a better shape than the pre-
PBP one, because Damian has brought a lot of good writing style issues up to
debate or discussion, and some of these became widely accepted best practices
/ red flags / etc. (see what I wrote here :
http://perl-begin.org/tutorials/bad-elements/ ). Naturally, you can still
write some relatively bad code after reading all of PBP and the online
discussion of best practices for Perl (and the recent trend of distinguishing
between "Modern Perl" and "Ancient Perl").
Should PBP be taken as gospel or dogma? Certainly not. I'm also not sure we've
seen the end of the advancements in what is not considered optimal in your
Perl code, and good Perl 5 code 10 years from now may be somewhat different
than today's.
And like I said earlier many of the discussions around what consitutes good
Perl code are actually "colour of the bikeshed" arguments, and not really
worth the mental effort (including some things that were said in PBP).
I should note that I don't refer people to PBP if I have not agreed with it or
think this is the case. I also don't refer people to other sources of "wisdom"
(e.g: Joel on Software, Paul Graham, or Larry Wall's talks), if I don't agree
with them or at least found what they said amusing (in which case I normally
add "but I disagree"). Let's keep the http://en.wikipedia.org/wiki/Ad_hominem
-s down to a minimum.
> > 2. As tchrist noted, I don't like changing the reference to the "foreach"
> > loop into a reference into a "for" loop. It's spelled foreach in Perl,
> > when refering to iterating over most elements, except perhaps a sequence
> > of consecutive numbers, where it resembles the most [citation needed]
> > common use of a C-style for loop , even if you call it for, and now may
> > exist in one form or another (but usually also spelled foreach) in other
> > languages that they may already be familiar with such as Java or C#.
> >
> > The general convention in Perl was that while both keywords were
> > equivalent you should write «for (my $x=0;$x<10;$x++)» (Yes, I know it's
> > not recommended to do it this way in Perl) and «foreach my $filename
> > (@list_of_fns)» because while «for my $filename (@list_of_fns)» is
> > acceptable and has existed using the for keyword in many languages past
> > and present, «foreach (my $x=0;$x<10; $x++)» is an atrocity.
>
> That's another "should" I don't think the documentation should be doing.
> "for" and "foreach" are aliases, and the documentation shouldn't pretend
> they aren't. And if people can't see the difference between
>
> C<< (EXPR; EXPR; EXPR) >>
>
> and
>
> C<< $variable (LIST) >>
>
> the for/foreach isn't going to help them.
>
> Also note that many people aren't consistent. Even people who consistently
> write C<< foreach my $var (LIST) {BLOCK} >>, they often write
> C<< EXPR for LIST >>.
>
Right. I don't mind C<< for my $elem (@list) >> instead of "foreach", though I
think we should still refer to it as the foreach loop. I still stand by my
point that C<< foreach (;;) >> is very bad style.
Regards,
Shlomi Fish
--
-----------------------------------------------------------------
Shlomi Fish http://www.shlomifish.org/
"Humanity" - Parody of Modern Life - http://shlom.in/humanity
Chuck Norris can make the statement "This statement is false" a true one.
Please reply to list if it's a mailing list post - http://shlom.in/reply .
Thread Previous
|
Thread Next