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

[J. Shirley]

On Sun, Apr 27, 2008 at 11:05 AM, Aristotle Pagaltzis <pagaltzis at gmx.de> 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.
>

Mapping a mountain when you need a mole hill is equally silly of an
analogy.  I don't think we need analogies to make our points.  If you
think that reading the Catalyst source is too much work, do as I said
and read the pod for the packages in the Catalyst-Runtime dist.

>  Did you ever notice that the only people who say this are the
>  ones who already know the code intimately?


And...  most people with enough energy have read it in the course of a
weekend.  It really isn't that complex to read the core bits.  When
you get into the attributes things get a bit more hairy.

>
>
>  > 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.
>

Nonsense.  I read the pod for the packages in Catalyst-Runtime (well,
before the split) before I ever looked at the Catalyst source.    It
is very simple.   Keep in mind, all of my points are about people
_requesting_ to learn the internals of Catalyst.  These are the best
resources, period.  If people don't want to read source or pod, they
do not really want to know the internals.

>  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.

Funny, I think that new vs. COMPONENT time is pretty well documented.
There is a document for Internals.
http://search.cpan.org/~mstrout/Catalyst-Manual-5.701004/lib/Catalyst/Manual/Internals.pod

While I agree that the design (in terms of pure OO) isn't the best, it
does work and I think it does make plenty of sense.  If you look at
the debug output on server startup, you can easily figure out what is
being loaded and how.

>  There is also a lot of indirection – for good reason, of course,
>  but readability suffers from it just the same.
>
>  As a result, a lot of the code is not nearly as self-contained
>  as it could be, which means that you need to already understand
>  a lot of the codebase before you can understand most of the
>  codebase.
>

Right.  If you want to understand the codebase you will have to
understand the codebase.  My point is that people may think they need
to understand the codebase when in fact they just need to not be lazy
and write better code.

>  It's by no means an insurmountable task (which is a happy side
>  effect of the modest size of the codebase and not in any way a
>  property of the design itself), but it would be miles easier if
>  there was a high-level overview of the architecture.
>
>  If no one else does write such a thing, I will, once I've come
>  out the other side. Depending on the extent of the task, it might
>  also lead to a patch or two to untangle and isolate parts of the
>  code from each other, although I'm not sure how far this can be
>  taken while respecting the stability/backcompat imperative.
>
>  But in the meantime please quit shifting the laziness blame to
>  the users.
>

If a user wants to know the internals without reading any code, they
are lazy.  Pure and simple.

This thread is about what goes into the next book.  I offered a
collaboration and proffered points as to why I think the idea of
documenting the internals in the form of a book is not a good idea.
Your disagreements(?) above are more about the difficulties in
understanding the internals, but that doesn't really address the point
that I brought up about the quality of a book discussing said
internals.

Then you call it laziness blame.  That's pretty confusing, to be
honest.  I think that it is far more work to collaborate between
Jifty, Catalyst, the various ORM guys and whoever else is relevant on
a BPB for Web apps, which seems to me to be a better book (both for
the publishers, authors and readers).  It's obviously something that
could be broken into multiple volumes (Frameworks, ORMs, General
Design in a Perl way, etc).  But to think that the internals need a
deadtree version, that's silly.  Internals should be in .pod; for
developers by developers -- not users.

-J