[Catalyst] Re: So, what do we want in the -next- book?

[Jonathan Rockway]

* On Sun, Apr 27 2008, Aristotle Pagaltzis wrote:
> * J. Shirley <jshirley at gmail.com> [2008-04-27 19:30]:
>> If you want to know the internals of catalyst, do as Jonathan
>> said and fire up a code browser and get started.
>
> Putting together a map of a mountain by examining it one pebble
> at a time is not particular efficient nor easy.
>
> Did you ever notice that the only people who say this are the
> ones who already know the code intimately?

Yeah, and we all learned it from a super secret book we're not sharing.

Here's how to learn the catalyst internals:

  1) Learn how to use OO Perl (read "Intermediate Perl")
  2) Learn how to use Catalyst (read my book)

Now you know how the pieces of Catalyst fit together, and you know what
OO is.  You're halfway there.

Now you figure out what you want to know.  "Hmm, I wonder how the :Local
attribute works."  Now you grep for "Local" and find
"_parse_Local_attribute".  Then you follow that path until you
understand it.  If statically reading the code doesn't do it for you,
stick in a breakpoint (or Carp::REPL) and start your app.  When you're
in there, poke the data structures until you understand them.  Then
continue reading the source.  Another good thing to do is try to add a
new feature.  It's not going to be easy the first time, but that's the
point of practicing.  You're not going to get good by reading books.
You're going to get good by reading the source.

Finally, a book about the internals might be worthwhile if we were sure
that This Is The Best Way To Do Things, but Catalyst isn't.  It's *a*
way that works, but certainly not the best.

If you want to read about "the best" read some of Knuth's books.  TeX is
a literate program.

>> Alternatively, just read the pod for all the Catalyst
>> components; they are very well documented and easy to
>> understand.
>
> Easy to say when you’ve been on personal terms with the codebase
> throughout its evolution. For someone completely new to the code,
> things are far less obvious.

Am I the only person here that has ever started a job and had to just
dive into the code, code without docs or tests?

I assume not, but nobody is asking your boss to write a book about how
your internal code works.  You just dive in and understand it.  Diving
into Catalyst is even easier, because it has docs, tests, and thousands
of working applications that use it.  (Search CPAN for "catalyst".  Lots
of people have figured it out.)

> As I try to make sense of the codebase I keep stumbling over
> places where the setup is quite incestuous: components often do
> not really set themselves up, they are just glorified structs
> that expect whoever instatiates them to do all the work. Which
> expectation is nowhere to be found in the docs – so much for
> “well documented.”  In OO design terms, this is really crummy.

As I said above... yeah... Catalyst sucks.  It is not God's Gift To The
World.  It's some useful code that works.

> But in the meantime please quit shifting the laziness blame to
> the users.

People are responsible for themselves.  If they want to understand
something, they can't expect understanding to be handed to them on a
silver platter.  They will just have to dive in and try to understand.

It's called programming.

Anyway, if someone wants to pay me $250/hr to document Catalyst's
internals, I'll do it.  But I bet you'll find that it's not worth it.

Regards,
Jonathan Rockway

-- 
print just => another => perl => hacker => if $,=$"