PHP Programming

I can't sleep, so I figured I'd wade into the inline documentation debate.

Travis states that programming languages are declarative, so code, along with associated unit tests are enough to define what the code does, as well as provide examples of how to use the code.

Well, I agree with that.

However, that doesn't mean that inline documentation is therefore a "bad thing". Tobias has pointed out a couple of reasons why that's the case. I can think of a couple more, too.

I was extending the Openads database abstraction layer last night, to ensure that creation of databases works correctly. I'm no PostgreSQL expert, but it seems that it won't let you issue DDL/DML commands unless you have connected to a database first - so if you want to create a database, you have to connect to a different, already existing database first.

Luckily, the PEAR::MDB2 library will connect you to the "default" database for a database server if you specify no database name in the DSN. (For PostgreSQL, this is the "template1" database.)

This was all well and good, until I tried to then connect to my newly created database, and all I'd get back was the previous connection to "template1". It turns out that the MDB2::singleton() method compared the DSN array of the database you want to connect to with any DSN arrays of previous connections it has made by using the array_diff() function.

Alas, when creating a connection with no database name results in the DSN having the boolean false for the database name field - and because other items in the new DSN array were also false in my case (for example, the "mode" of the connection" was false), the array_diff() function returned no differences. Oops!

Changing to the array_diff_assoc() function solved the problem.

It's been all systems go at Openads central this year. One of the big jobs we've been taking on is dealing with our database schema. Managing database schemata is actually a tough job, if you want to do it in a agile way. (No one actaully designs their database schema up front any more, right?) There are several great books on the subject, though, and based on those ideas, we've produced a white paper outlining a system we're writing for managing database schemata for PHP, in the same vein as Rail's Migrations.

As part of this project, we've decided to use PEAR::MDB2 and PEAR::MDB2_Schema to manage the jobs of reading in our existing database schemata from existing databases, to then be stored in XML files, The same two PEAR packages will then be used to prepare the SQL DDL/DML commands required to create new databases when installing Openads, or to modify an existing Openads database when upgrading. Of course, the DDL/DML created will all be based on XML schemata files.

If you've ever used PEAR::MDB2, you may be aware that it works by storing database schemata information in an "internal" MDB2 datatype. This datatype needs to be converted into database-specific commands when talking to a database, obviously. But if you're reverse engineering a schema from an existing database, you also need to be able to convert an existing database "nativetype" into the appropriate MDB2 datatype.

However, this is where we've run into a few issues.