develooper Front page | perl.perl5.porters | Postings from March 2011

Re: Revising Perl's OO docs - a new OO tutorial

Thread Previous | Thread Next
From:
Aristotle Pagaltzis
Date:
March 6, 2011 14:39
Subject:
Re: Revising Perl's OO docs - a new OO tutorial
Message ID:
20110306223930.GH19109@klangraum.plasmasturm.org
* Dave Rolsky <autarch@urth.org> [2011-02-28 21:50]:
> I've been working on a new OO tutorial for Perl. This is part
> of a larger goal for the Perl docs to revise all of the
> existing OO documentation.
>
> My new document is available online for review:
>
>   http://urth.org/~autarch/new-pod/html/perlootut.pod.html
>   http://urth.org/~autarch/new-pod/pod/perlootut.pod

I’m sorry: I hate it. It’s just weak. There’s a lot of a weasel
language trying to excuse the old way for sucking, without saying
it sucks, and meanwhile trying to sell the new way, without quite
invalidating the old way.

I don’t think that’s how it should read.

All that stuff about the historical whys?

Nobody cares.

Us old fogies might, but novices will wonder why they’re told how
it used to be: what does it matter to them? It doesn’t make any
difference to the code they’re writing, does it? So why are they
getting a history lesson?

I also agree with others who say that having an idea how things
work under the covers is imperative to a confident grasp of how
to do OO in Perl 5, even with Moose. An explanation of the old
way need not amount to telling people to do it like that. It’s
perfectly possible to convey how packages, functions, references,
`bless` and method dispatch relate to each other without a full
tutorial on how to make use of them bare-bones.

If nothing else, there is a lot of non-Moose OO code out there
already. People newly tasked with maintaining such code should
not be left stranded by the documentation. At least hash-based OO
done the old way should be accessible to someone coming to Perl 5
as a novice maintainer. I wouldn’t want them itching to rewrite
working code just because it’s “not how you do it”; no need to
fuel NIH.

The documentation should make no excuses and no value judgements.
Perl 5 is what it is; deal with it; here’s how. That’s what its
stance and aim should be.

So all it should do is explain how things work, go into the old
way long enough to explain hash-based objects (but leave other
kinds of referents to a footnote), and proceed to cover Moose as
the practical way of doing OO now. The history lesson should be
put off for an appendix though it’s OK to have one there – it can
help grasp how Perl 5 as a language hangs together.

The community fashion wars have no place in the document.

As for the general intro to OO: it’s too short and falls back on
that useless “an object is a thing, like a person” explanation.
I ranted about that long ago: <http://plasmasturm.org/log/340/>.
As a concrete example from computing I suggest a windowing system
(which, no coincidence, is more or less what inspired OOD at
all). Any good intro should also probably contain something like
Damian’s 11 rules for when to use OO.

Sorry I am so sharply critical and don’t have any real praise.
I completely agree the premise of the effort, I just think the
text of this document is a long way from core-worthy. Its outline
covers all the area it should and much of the material is useful,
so something vaguely resembling it (minus mealy-mouthed politics)
would be good. Just not this one, unedited.

If we just delete all the bad tutorial material from core, that
would be a step in the right direction.

Regards,
-- 
Aristotle Pagaltzis // <http://plasmasturm.org/>

Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About