Code flow doc (was: Re: [wp-hackers] Google Summer of Code 2008)

[Jennifer Hodgdon]

Dan Larkin wrote [snipped]:
>  [...] I guess my aim is to
> completely flesh out that Query Overview page, and then some.
> 
> It does a good job of starting the explanation, at least for the non-admin
> pages.  What I'd like to see is a group of pages that explains not only what
> the main functions are, but also what these functions do in detail.  I'd
> like to see a document specify which filters and hooks are run at which
> point in the process, and what they can be used for.  I'd like to see
> case-specific data paths.  [...]
> 
> From what I understand, WP is designed to be accessible.  A project with as
> many lines of code as WP is inherently inaccessible.  In economic terms,
> it's an oligopoly for experienced developers - there is a pretty high
> barrier to entry  [...]

A few more thoughts here...

Yes, there is some barrier to becoming familiar with the core 
WordPress code base, but that is true in any large-ish open-source 
project. If you want to participate in the role of a core developer or 
bug patcher in any open-source project, you have to be willing to read 
source code. Is that a problem? I don't think so -- only people who 
have familiarized themselves with the core source code and who can 
read reasonably well-written code in the project's language should be 
proposing changes to it, and yes, it does take time to familiarize 
yourself with any fairly large code base. The code of WordPress is 
written in a pretty clear manner, in my opinion... It could be better 
documented (there are efforts underway to add PHP Doc headers to all 
the functions, another good SoC project), but if you can read PHP, I 
don't think it's difficult to figure out what any individual function 
does by reading the code.

Also, if you have a reasonable IDE on hand (such as Eclipse), if there 
are functions called that you are unfamiliar with, it's pretty easy to 
search for them and find out what they do.

My thought when I wrote the Query Overview page was to present a road 
map to how visitor-facing pages are generated, which I didn't think 
was obvious, even after spending the time to read through the code in 
detail. I thought that at least it would give someone a head start (at 
least tell them where in the source code to read to find more details).

The reason I haven't made something like Query Overview to explain 
what the admin pages do, is that I think it's a lot clearer there: you 
visit a particular admin page URL, and that tells you which source 
file is being used to generate that page. Then go read that file to 
see what it does.

My concern on making a document like what you describe, which goes 
into great detail on the flow, functions, hooks, etc., is that my 
experience in years as a professional software developer has been that 
the code itself is the only reliable "documentation" of what the code 
is doing in detail. Any attempt at having outside documentation 
explaining the code may be fine at the moment it's written, then 
quickly goes out of date.

Thoughts?
     Jennifer

-- 
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com

Drupal/WordPress Sites, Themes, Modules/Plugins
Custom Web Programming, Web Databases
Modeling/Analysis/Palm OS Software