[wp-hackers] Inline Documentation Effort was a Failure

[Eric Marden]

Jacob,

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.

-e