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

Tue Feb 26 23:46:56 GMT 2008

I have to agree with Jennifer because she is right. If what you propose
was done it would be one of a kind in an open source project. I'm starting
to see the arguments for why it should and how. I don't think it must be
as detailed as you would want.

It isn't so much as you want, but what you need as a developer. If you
only want the quick and dirty then you don't need work flow that is very
detailed. I think it would make sense to have a summary work flow of the
comments and popular, most used sections.

The problem then is choosing which parts you want to have a work flow and
which parts aren't used as often to justify a work flow. Work flows don't
have to be as detailed to need to be updated that often.

If I get Visio, I'll be willing to provide summary work flows of the most
used sections.

Of course, if the functions are properly documented, then they will have
@uses and @usedby tags. Not all of the functions have these because the
time needed is far more than I was willing to devote. However, a lot of
the functions documented during late December/early January do have @uses
apply_filters(), which document hooks.

I will suggest creating a phpDocumentor site for WordPress and checking
out the results, because a lot of the work flow is probably there already.

I think for most places, most of the functions don't have that many
dependencies, so following the paths aren't that difficult. However, many
functions have a lot of branches which are difficult to follow. So even
with the classes, following the work flow shouldn't be that big of a task,
except for finding where the function exists in which file (and again, I
suggest using phpDocumentor).

> Well, I do understand what you're saying about it going out of date.  That
> is the main problem with documentation - that it needs to be maintained.
> This is true of inline documentation as well.  It's never really an easy
> process.
>
> My point to making this documentation wouldn't be to facilitate the core
> developers.  They obviously already know how things work.  As I said, I'm
> proposing it to help out the casual developers - the people who are trying
> to write a plugin or two for their site, but can't figure out how to make
> WP
> do what they want, or the people who are trying to figure out what filter
> they really need to, or to add extra functionality that they would have
> thought should be in the core but they found isn't.  I know from my
> limited
> experience writing plugins for WP, it can be pretty frustrating trying to
> figure out how the actual code handles things that are pretty simple when
> talking on the abstract level, just because things are sent around through
> so many different functions and filters.  I mean, yes, you can use search
> tools to figure out which file a function is in, but when you have to do
> that like twenty times and figure out what each function is doing along
> the
> way, it can be pretty discouraging.
>
> Think of the WP motto.  "Code is poetry."  Yes, specially trained readers
> (and/or literary geniuses) can read a poem, analyze it, and come out with
> the meaning quite quickly.  Take a high school class.  You have a couple
> kids who are going to end up as English majors.  You won't find them
> complaining.  There's twenty-odd other kids in that class though.  Sure,
> maybe ten of them don't give a crap about poetry, but there's others that
> would love to get the meaning and just are having trouble with it.  They
> can
> get it eventually, but it takes them a lot longer.  That's what Sparknotes
> are for.  That's what I'm proposing.  And while they may not rely on it,
> those couple future English majors like having Sparknotes around every now
> and then as a quick reference.  It benefits everyone.  The only person who
> really suffers is the one making the notes, since he or she has to shell
> out
> the time.  I realize this analogy breaks down where poetry usually doesn't
> change so much so often, but that just means more time spend by the
> note-takers.
>
> Once the main effort is put out once (which a full-time job for a summer
> should be quite a step in that direction), then only a fraction of it must
> be spent with each subsequent code release.
>
> Maybe I'm trying to cater too much to the entry level WP hacker for the
> taste of those on these lists (since most people here are veterans), but
> it's my two cents so I'm throwing it out there.
>
> :: Dan Larkin
>
> On Tue, Feb 26, 2008 at 1:00 PM, Jennifer Hodgdon <yahgrp at poplarware.com>
> wrote:
>
>> 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
>>
>> _______________________________________________
>> wp-hackers mailing list
>> wp-hackers at lists.automattic.com
>> http://lists.automattic.com/mailman/listinfo/wp-hackers
>>
> _______________________________________________
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-hackers
>

-- 
Jacob Santos

http://www.santosj.name - Personal Blog
http://funcdoc.wordpress.com - WordPress Function Documentation Blog