Even on projects with extensive generated documentation, I find that kind of documentation to be of extremely low value. The problem with inline API documentation is that there is no sense of priority. Developers are encouraged to document every element that can possibly be documented. Then, when the documentation is generated, there is no way to distinguish the important from noise.

Another problem is restating the obvious. When a property or method really is well named, there may not be much more to say in the docblock. But, the mechanics of docblocks invites the programmer to say it anyway. So, you end up with comments like “$widget the widget.”

Duplication is also a significant problem. If you inherit from a base class or you implement an interface, there is a tendency to copy and paste the doc block from the parent to the children. This is an obvious maintenance problem. In fact, this is one of the major problems with comments. If comments restate what the code does, its a form of code duplication. When the code is changed, it requires changes in the comments. In this sense, comments make code harder to maintain.

Lately, I’ve been trying to curb the attractive nuisance aspect of docblock comments by replacing docblocks with comments like

 
// Definition in parent
 

 
// docblock intentionally omitted.
 

Well, if docblocks are so bad, what is the alternative? Well, I’ve tried a few, including using a wiki for API documentation. Here is the problem. If duplication between the comment and the code is created by inline documentation, that maintenance problem becomes significantly worse with distance. If the documentation is external to the code, that distance really harms the ability to keep the documentation in sync with the code. So, docblocks are bad, but everything else is worse.

Docblocks were popularized by Sun and Java (or maybe Donald Knuth). But when sun was documenting their Java APIs with docblocks, they had a professional documentation team to do the work. When teams that don’t have a dedicated documenter role use these tools, I think they fall short.

So what is the solution? I’d like to see better techniques and conventions for solving the problems of docblocks: avoiding duplication, avoiding restating the obvious, and avoiding the tendency to docblock everything thats docblockable. Maybe there are more successful documenters out there who are handling these API documentation anti-patterns better than I am. I’d sure like to hear how.

I really don’t know much about PDO, i haven’t used it yet. Most of what I know comes from:
Wez Furlong’s first steps with PDO examples
Wez’s Oracle PDO Article
John Lim’s discussion of adodb and PDO
A sitepoint thread on PDO
I haven’t seen any API type docs yet. I did download an older version of the PECL code and skim through it.

Alan has some interesting things to say. I have to agree with him on using libgda as a back end. Using a more mature, existing, debugged code base seems very reasonable to me. Could libgda be used as the PDO back end while retaining the PDO front end API?

When I first looked at PDO, the parameter binding is one of the things that really jumped out at me. It reminded me of register globals, a technique that didn’t necessarily turn out well and was painful to back out of. Now that Alan says it, this technique is a bit more reminiscent of C than PHP. As i understand its an optional way to use PDO. A way that I would not use.

Wez comments:

- copying C: I agree that bound parameters can lead to magic code. There are two things to keep in mind: a good coding style (with comments) is the best remedy for code that might be considered magic.

I have to strongly disagree on the coding style point. Salting magic code with comments does not make it palatable. The solution is to remove the magic.

I am not familiar enough with PDO to understand the iterator argument. None of the examples I have seen actually use iterators.

What I would like to see out of a basic OO DB API in PHP is better support for translating the database record into an object. For example, the fetch(PDO_FETCH_OBJ) method returns an anonymous object. I would like a way for this method to construct an object of a particular class along with an initialization protocol such as unserialize has with objects.

I do think that PDO should be a part of core PHP, but perhaps one with a more mature libgda backend and a more evolved PHP front end API, influenced by Alan’s feedback and DBDO efforts.

I have noticed that sometimes the API design in PHP tends to simply wrap underlying 3rd party C libraries, even when that design doesn’t make the most sense in PHP. (for example the PHP wrapping of expat) PDO is a more of an attempt to design a PHP oriented API and then work the 3rd party libraries into the common design. To me, this is a step forward. However, the PDO API probably needs to go through a few iterations as Alan suggests before being frozen into core PHP.

And we didn’t get out a 5.0, and that cost of us everything, it was the biggest mistake ever

This was obviously an emotional issue for Scott, and I think he is right.

Engineer types seldom recognize the incredible risk involved with embarking on a rewrite of an existing, working application. Joel’s point, is that Microsoft is making a similar mistake with their APIs today.

Harry speculates that PHP may be able to pick up some of the market share loss that this type of mistake could lead to.

good API designs happens when designers think of … client programmers as users.

I wish more developers took this to heart. I’ll add my own law of API design:

Good API design makes common things simple while leaving uncommon things possible.

You can call it Moore’s law.

When comparing two API possibilities, I often just count characters in a couple common examples of usage. To me, the API choice that results in fewer characters for the client programmer is usually the better API. This can tip the balance for subtle choices, or help evaluate two libraries which do the same thing.