PHP in Action

Feature-revealing code

dagfinn | 01 September, 2005 13:02

Making names "intention-revealing" is a well-known principle in object-oriented programming and design. You want the names of methods to communicate their purpose rather than their technical implementation.

A related question is: how much should the code reveal about what's going on at a lower level?

An illustrative example is the PEAR package HTML_Quickform, which handles all the essential tasks related to Web forms. Here's an ultra-simple example: create an HTML_Quickform object and add a single text input element to it.

$form = new HTML_Quickform;
$form->addElement('text','headline','Headline:')

This looks very straightforward, but the obscure thing about it is that this code also handles the HTTP request.
The documentation says that the constructor "loads submitted values". The intended use is the following:

The form object generates the HTML code for the form.
Then the user submits the form.
The POST request generated by that form submission is handled by re-creating the form object, using exactly the same code that we used to create it in the first place.

What the form object does in step 3 is populate the elements it contains with the values from the HTTP request. So it's ready to generate the complete HTML code for the form, a second time, containing the values the user entered in the form the last time around.

But when does the form object do this? The constructor "loads submitted values", but at this point we haven't added any elements to load the submitted values into yet. After studying the HTML_Quickform.php file, I believe what it does is store the values from the HTTP request inside itself, and then try in vain to insert them into the non-existent form elements.

But when do the elements actually receive the submitted values? When they're added, as far as I can tell. This is the kind of code that works, but it's hard to know how.

I would prefer to do this:

$form = new HTML_Quickform;
$form->addElement('text','headline','Headline:')
$form->populateWith(new HttpRequest);

That would make it possible to understand what's happening simply by reading the application code. (It would have a couple of other advantages as well, including easier testing.)

The API hides more than is useful for the sake of making the code readable and understandable. It's excessively convenient; I may save one line of code under normal circumstances, yet that line would be worth having as documentation of what's going on.

Obviously, hiding various mechanisms in form handling is the whole point of the API. But this--populating the form with values--is a major feature of the HTML_Quickform class. Therefore, it would be better if that were made explicit in the application code. That's what I mean by feature-revealing code.

Share and Enjoy:These icons link to social bookmarking sites where readers can share and discover new web pages.