[wp-hackers] Inline Documentation Effort was a Failure
wp at xentek.net
Sat May 24 06:36:01 GMT 2008
I applaud your efforts to promote writing phpdoc blocks as a matter of
programming best practice, but there is a good reason why its not
being done consistently: the developers (most of whom are volunteers)
have better things to do. Plain and simple.
I am a developer with 12 years of professional programming experience.
My last two positions have been as tech leads, and I have been
responsible for crafting the standards for my team. And if there is
something I have learned from that role: you can't force policies on
developers if they don't see the value in them. There has to be
universal buy in from all the developers. The other thing I've learned
is that you don't have to implement all best practices in order to
have a successful team/project/code base.
The other thing to keep in mind is that best practices don't look the
same on every project. In fact, they need to be customized to fit the
work at hand. Wordpress, both its developers and its fearless leader,
just happens to prefer documentation living in the Codex instead of
phpdoc blocks. It gets them more bang for their buck, as more people
will be using it in their day to day usage than looking at the code.
I've been building sites and blogs with wordpress since the 1.5 days,
and have always found the Codex to be more than adequate for my needs.
In fact I trumpet the wordpress API - as represented by the Codex - as
the mark of a brilliantly executed open source web app. Sure,
generated documentation would be helpful to new people looking to
start committing to the wordpress project, but that's a much smaller
audience that the people looking to just extend and customize WP for
their needs. For that group, the codex is just fine, and the WP team
recognizes that fact. Indeed, this is a primary example of an agile
development philosophy - and one that resonates with my own
development methodology. This is obviously a deliberate decision made
by those stewarding the WP project into the future, and one that works
fine for 99% of the users.
> I'll probably fork WordPress long before that happens.
Just because the developers aren't writing phpdocs? That seems rather
stubborn and dogmatic. There are more interesting things to do on the
project, and any of them will provide more long term value than
generated documentation. But if you feel that strongly that they
should be written, then provide a good example, document others code
when you can, and evangelize the benefits of the practice. But don't
expect developers to react favorably to coercion and bullying.
More information about the wp-hackers