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

[Aristotle Pagaltzis]

* 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?

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

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.

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.

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.

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