In The importance of bad code (or, WordPress and why I am a psychic), Marco Tabini proposes the idea that we need bad code. Or at least that we should be tolerant of bad code in open source projects because that invites participants that might otherwise not contribute.

This is an interesting idea that struck me as novel. But after thinking more about it, I believe it’s not a radical departure from what we’re all implicitly accepting, no matter how fanatical we might be about clean code.

Luke Welling’s comment to the blog post is particularly enlightening and worth quoting in full:

I’d argue that bad code is often a sign and a side effect of a thriving, welcoming user community around a project.

The OSS projects with good code tend to have a relatively small group of committers doing nearly all the work. There is a big learning curve to
working within the project’s (probably unwritten) architectural guidelines, and a big reputation curve that a new person has to climb
to get their patches accepted.

Bad code is often a sign of welcoming new contributors, taking patches that do something useful even if the approach is ugly.

We  all know the problems bad code brings, but I would argue that some  projects are not just successful in spite of bad code, but successful  because they allow bad code.

I commented:

If  we’re looking for the optimal strategy (which is likely to depend a lot  on the specific project), the question may be what parts of the code  need to be held to high quality standards, and what parts don’t require such strictness. And how to separate the two. Security is one of the key issues, since bugs can hide in bad code, and some of those will be security bugs.

Perhaps even more important is the question of whether and how to keep a clean separation between good and bad code. Bad code becomes a problem to me mainly when I need to maintain bad code written by others. Not that I dislike it so much; I sometimes enjoy cleaning up messes, but it slows me down. But if the person who wrote it is maintaining it, it doesn’t affect me much. So a clean separation would be helpful.

That also makes the whole issue clearer to me. Most of us use operating systems, library software and applications that aren’t necessarily up to our coding standards. Having lower code quality in parts of a project is not much different in principle. In fact, it may be less of a problem in some cases. When you a program library that has code of poor quality, the good code is dependent on that bad code. If you are programming the core of an open-source project and someone else is adding bad code in the form of an extension, the bad code is dependent on the good code, making it even less likely that the bad code can affect the good code.

In Domain-Driven Design, there is a pattern called Anti-Corruption Layer which can be helpful in preventing the bad code from having an undue influence on the structure of the good code. It’s worth thinking about, especially when the bad code has an illogical and confusing API.

Dean Wampler blogs: Is the Supremacy of Object-Oriented Programming Over?

“The fact is, for a lot of these applications, it’s just data. The ceremony of object wrappers doesn’t carry its weight. Just put the data in a hash map (or a list if you don’t need the bits “labeled”) and then process the collection with your iterate, map, and reduce functions. This may sound heretical, but how much Java code could you delete today if you replaced it with a stored procedure?”

After the previous post in this series, additional independent implementations of the idea of JavaScript-style classes have turned up. So I’m going to list them and comment briefly on the differences. I hope this will be helpful to anyone who actually wants to use this in practice and needs to decide on the details of the implementation. Here are the links in chronological order:

• Ionut G. Stan:Javascript style PHP with PHP 5.3.0 (forum posting).
• Fredrik Holmström: Javascript-OO & Python-DuckTyping in PHP5.3.
• John Mertic: What’s new in PHP V5.3, Part 2: Closures and lambda functions.
• My own previous article.
• Andrea Giammarchi: A JavaScript Object Like PHP Class.

One difference is how JavaScript-like the implementations are. Some of them implement a syntax that is deliberately made to resemble JavaScript. Andrea Giammarchi’s version even uses ArrayAccess to make it possible to access object properties using both object and array syntax, as in JavaScript. At the other extreme is my implementation. I’ve tried to make it as similar to a regular PHP class as possible. You can instantiate an object in the same way as with an ordinary PHP class. This comes from defining the methods inside the class constructor.

After seeing all of these, I prefer my own way of doing it, except that it lacks what I mentioned in the previous article: an exception when you try to call an unrecognized method. But I’m obviously not objective, and I may have have missed something.

Davey Shafik discusses return values from functions. In the specific case of a function that returns values from a database, he wants to return false on error and an empty array if the data set is empty. He also has a reason for that:

“However, it’s very rare that I care about whether I hit an error condition or just got no result when it comes to display — more to the point, my user doesn’t care.”

That’s interesting, but I think that someone trying to understand the code might care. It might be easier to read if the two cases were somehow handled separately, at least at the lower levels.

What does help, as pointed out by several commentators, is to throw an exception instead of returning false. The book Clean Code recommends throwing exceptions instead of returning error codes. That gives you flexibility in handling the error. It can be handled at a higher level without having to clutter the levels in-between with error handling code.

In general, it’s often a good idea to return values that don’t require any special handling by the calling function. An empty array is an example. Foreach loops will happily do nothing, and everything runs smoothly, although you may need to check for emptiness at some point (typically to give a message such as “no records found).

Here are some general recommendations for handling return values in PHP. I’m sure they’re not perfect, but at least I can enumerate a number of alternatives.

• Data set. Return an array (empty if no data is returned). If the data set can be very large, return an SPL iterator that can be used interchangeably with an array in foreach statements. Or, if you have a good reason to do so, return some kind of data set object (Zend Framework does this).
• Error condition.  Throw an exception. Or, if it’s not really an unexpected error, consider letting the calling code test for the error condition before calling the function in question.
• Single value. If you return a data structure as an associative array, it may be useful to return an empty one if nothing is found. Even more interesting is the Null Object pattern. If you would normally return a Contact object and the query returns nothing, return a NullContact object that has null operations and will return false if you call isNull() on it.

Technorati Profile

As one of the critics expressed it:

No, comments are there to comment. Period.
That has nothing to do with how good is your code.
You can write perfectly clean code and add good comments to it. Nothing wrong with that.

This is one of those ideas that seem obviously true in theory, but fail to work in practice. The reason is that comments get out of sync with the code. The comments rot, or rather, their meaning does. They become more and more misleading as the code gets changed and the comments are not adequately updated.

Let me give you an example. But first, I want to make it clear that I don’t think code comments are always a bad thing. Sometimes, they are necessary. But much less often than people think.

API documentation is often indispensible, but that’s really a different matter. When API documentation is generated from comments in front of each method, the primary purpose is to explain how the code can be used, not how it works. In fact, you might say they are code comments only in a syntactical sense.

On to the example. One of the comments to my blog post presented a code snippet that illustrates my point well. It’s supposed to be a example of a useful inline comment in code.

// first handle the case where no records were found
if ($records == 0) {
    return false;
}

Is this really an case of good commenting? I don’t think so. If it’s hard to understand that $records == 0 means that no records were found, we can change the code to make it easier. The simplest way to do it is to rename the variable to something like $numberOfRecordsFound or $numRecordsFound. Or extract a method. But typically, it’s possible and preferable to avoid this kind of check altogether.

Anyway, the comment is unnecessary. But as I only realized a while later, it’s also misleading. Does the code “handle the case where no records were found”? No, it leaves it to the calling function to handle the case. The one line that returns false is not handling anything, it’s just passing a message.

So the comment is already misleading, never mind what will happen when someone changes the code and neglects to update the comment. For example, let’s say the next programmer to work on this code is in hurry to fix a bug. Now maybe the code will look like this:

// first handle the case where no records were found
if ($records == 0 && $state == ACTIVE) {
    return false;
}

The programmer wonders briefly whether the comment is still fully appropriate, is unsure, and decides to do nothing about it (or postpones the decision and forgets about it). Now, perhaps (we can’t quite tell without the full context), the comment is even more misleading.

In the next round, yet another programmer comes along, makes some more code changes and wonders: “Should I update the comment? It looks all wrong to me, but it was probably written by someone with deeper insignt into the code. Better leave it alone.”

The code would have been better off without the comment, but no one wants to delete it, especially since they have been told that comments are so important. It’s a downward spiral: the code changes make the comments misleading less chance that they will

Comments that lie are worse than no comments, and in practice they tend to big liars.

Unfortunately, he’s at least 10 years too late. This used to be good advice, but not any more.

Up to a point, he’s right. Making code as easy to understand as possible is essential and can save a huge amount of time later. And adding comments to unreadable code is better than leaving it the way it is.

There is a better way, though. Refactor your code so it’s easy to understand even without comments. I’m just reading Robert C. Martin’s recent book Clean Code. He is very clear on this point.

Clear and expressive code with few comments is far superior to cluttered and complex code with lots of comments. Rather than spend your time writing the comments that explain the mess you made, spend it cleaning that mess.

The principle is simple: if you have an inline comment in a method (or function), take the chunk of code that the comment refers to and extract it into a separate method. Give the method an intention-revealing name. Typically, you won’t need the comment afterwards.

I’m sure we need an example. Here’s a small excerpt from a method taken from Zend Framework.

protected function _doUpdate()
{
...
        /**
         * Execute cascading updates against dependent tables.
         * Do this only if primary key value(s) were changed.
         */
        if (count($pkDiffData) > 0) {
            $depTables = $this->_getTable()->getDependentTables();
            if (!empty($depTables)) {
                $db = $this->_getTable()->getAdapter();
                $pkNew = $this->_getPrimaryKey(true);
                $pkOld = $this->_getPrimaryKey(false);
                foreach ($depTables as $tableClass) {
                    try {
                        @Zend_Loader::loadClass($tableClass);
                    } catch (Zend_Exception $e) {
                        require_once 'Zend/Db/Table/Row/Exception.php';
                        throw new Zend_Db_Table_Row_Exception($e->getMessage());
                    }
                    $t = new $tableClass(array('db' => $db));
                    $t->_cascadeUpdate($this->getTableClass(), $pkOld, $pkNew);
                }
            }
        }

By changing some temporary varibles into instance variables and extracting a couple of methods, we can get code like this:

if ($this->primaryKeyValuesHaveChanged() {
    $this->executeCascadingUpdatesOnDependentTables();
}

Or even, by extracting a couple of classes, making objects out of two of the concepts involved, we might end up with something like this.

if ($primaryKeys->valuesHaveChanged() {
     $dependentTables->executeCascadingUpdates();
}

This uses most of the words from the original comment, but it’s superior for several reasons. First and foremost, the section of code as a whole is clearer. Second, comments have a tendency to get out of sync with the code. By expressing the message in the code itself instead, we can avoid that. Third, the extraction itself has the positive side-effect of making it possible to test the extracted method in isolation.

Improving the code itself is harder than writing comments, but it’s worth it. .

call_user_func($_REQUEST['action']);

Warning: Do not use this in a real application.

There is one and only one good reason why you shouldn’t: it’s totally insecure. Except for that, it’s simple but perfectly viable. Your actions will be just plain functions, which is pretty simplistic and will be hard to handle if you build many of them. But it’s a huge improvement over the average PHP script with no systematic handling of the PHP request.

If you want to do something more like the frameworks such as Zend Framework, you want your actions as methods grouped into classes (called Controllers in ZF).

Now you need two lines. The following script demonstrates this:

// Pretend we have an HTTP request
$_REQUEST = array('controller' => 'Contacts', 'action' => 'edit');

// Front controller
$controller = new $_REQUEST['controller'];
call_user_func(array($controller,$_REQUEST['action']));

// The action controller class
class Contacts {
    function edit() {
        echo \"ok\n\";
    }
}

You can start with something like it (assuming that security has been taken care of) and add features as you need them.

In case you’re wondering how to what exactly the security issues are, the most obvious problem is the fact that any user can run any method in any class that is available to this script. The way to avoid that append or prepend some fixed string to the class and the method name. For instance, in Zend Framework, the action name edit will activate the method editAction().

Beyond that, the security problems are the usual ones. You need to filter input, And in general you should beware of $_REQUEST, since it can also contain cookie data.

Anyway, Uncle Bob held an extremely entertaining and useful introduction to the FitNesse testing tool. He got me hooked on it, but I’m even more fascinated by something else. I asked him, “what is the nature of the test API [you've been talking about]?” He answered that question, and also another, more general one: What is a good strategy for complete automated integration and acceptance testing of an application? That was the question I really wanted to ask, only I wasn’t quite aware that I wanted to ask it. And, impressively, he answered it anyway.

As I understood it, the strategy he outlined was as follows. The diagram is probably only a mild perversion of the one he drew on the whiteboard.

• Test all features through a test API just underneath the user inteface. These are the main acceptance tests; the ones that are used to decide whether a feature is done or not done yet.
• Test the user interface in isolation, running calls to a fake system underneath.
• Run just a few tests all the way through the application to test the plumbing between the user interface and the rest of the system.

The reason why we don’t want all our acceptance tests to go through the user interface is that the user interface has a tendency to change often, and changes in the user interface tend to breaks lots of tests.

This resonates reasonably well with my experience, although I think testing “everything” through the user interface can work sometimes, if the user interface is a very plain one.

In addition, we want unit tests for each small piece of the application. The tests outlined above are just catch the few bugs that are not detected by the unit tests.

So am I wrong? Did I get carried away? Did my critical faculty go on vacation somewhere nice and sunny? I admit that sometimes I deliberately look at the positive and ignore the negative. (And sometimes I do the opposite; It’s a good exercise if you’re careful.)

I wasn’t drunk, anyway. But let me take a closer look at the particular line of code I was praising:

$this->assertThat($form->hasSelect(withName('statusConfirm'))->hasValues(),
    array('Yes','No'));

My main point is that it’s close to plain English. Not everyone agrees that that’s a good thing, but I argue that we’re built (genetically wired, in fact) to understand natural languages, not program code. Therefore code should be easier to understand when it approximates natural language and expression. And we’re trying to create or approximate a Domain Specific Language (DSL), which should express exactly what’s required for the domain and not the demands of the technical implementation.

So for this experiment, let’s translate this one into a (plain English sentence:

Assert that Form (this particular one) has a select menu with the name “statusConfirm” and values “yes” and “no”

Translating back into code, it might look more like this:

$this->assertThat($form)->hasSelect()->withName('statusConfirm')->andValues('yes','no');

To me, this is even more natural than the other one. I think we’ve gotten rid of some syntax that has to do with implementation details rather than making the API simple to use.

It also seems clear to me how this could be implemented. All of the method calls could be to an assertion object that would take all these various inputs and always return itself at the end of the method so you can chain the calls in what’s known as a fluent interface.

Implementing automated tests by using Seleniums API methods has several drawbacks. Selenium is great for what it does, providing a generic framework for testing a generic application. Using the Testing_SeleniumDSL framework, I will show you how to create your own Domain Specific Language (DSL), which would allow you to write tests in the language of your business rather than in Seleniums language.

I’m quite impressed by the examples he presents, such as:

$this->assertThat($form->hasSelect(withName('statusConfirm'))->hasValues(),
    array('Yes','No'));

This is truly expressive, readable code. I’ve refactored web test code in this direction many times, but I admit I never got quite this far.

The DSL is planned as an open source release. It would be interesting to try something similar for the SimpleTest web tester, which is my favorite for testing web interfaces without too much JavaScript. (Based on the paparrazzi principle.)