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.

My previous example in part 2 was just “hello world”, so I’m going to try for something more like the real world. You may find this example unusual, but it does work. I took the PageRange class I used in my July 2007 php|architect article and converted it to the JavaScript style. The class is a variation on Martin Fowler’s Range pattern, and is the hub of a re-implementation of the main functionality of PEAR Pager, using a more object-oriented style.

A Range object is defined by just two values (three in my variation), so it might seem like too much to have an object just to keep these values, but as you can see from the example, a Range class can have behaviors to change and compare ranges.

As before, I’m defining most of the methods inside the constructor.

<?php
class PageRange {
    public $start;
    public $end;
    public $length;

    private $moveToStartAt;
    private $moveToEndAt;
    private $changeLengthToEndAt;
    private $includes;
    private $isInside;
    private $extendsBeyondStartOf;
    private $extendsBeyondEndOf;
    private $truncateToFitInside;
    private $moveToFitInside;
    private $asArray;

    public function __construct($start,$end,$length) {
        $self = $this;
        $this->start = $start;
        $this->end = $end;
        $this->length = $length;

        $this->moveToStartAt = function($start) use ($self) {
            return PageRange::withStartAndLength(
                $start,$self->length);
        };

        $this->moveToEndAt = function($end) use ($self) {
            return PageRange::withEndAndLength($end,$self->length);
        };

        $this->changeLengthToEndAt = function($end) use ($self) {
            return PageRange::withStartAndEnd($self->start,$end);
        };

        // Comparisons

        $this->includes = function($page) use ($self) {
            return $page >= $self->start
                && $page <= $self->end;
        };

        $this->isInside = function($range) use ($self) {
            return $range->includes($self->getStart())
                && $range->includes($self->getEnd());
        };

        $this->extendsBeyondStartOf = function(PageRange $range) use ($self) {
            return ($self->getStart() < $range->getStart());
        };

        $this->extendsBeyondEndOf = function(PageRange $range) use ($self) {
            return ($self->getEnd() > $range->getEnd());
        };

        // Changes

        $this->truncateToFitInside = function(PageRange $larger) use ($self) {
            if ($self->isInside($larger)) return clone $self;
            return $self->changeLengthToEndAt(
                $larger->getEnd());
        };

        $this->moveToFitInside = function(PageRange $larger) use ($self) {
            if ($self->isInside($larger)) return clone $self;
            if ($self->extendsBeyondEndOf($larger))
                return $self->moveToEndAt($larger->getEnd());
            if ($self->extendsBeyondStartOf($larger))
                return $self->moveToStartAt(
                    $larger->getStart());
        };

        // Convert to array

        $this->asArray = function() use ($self) {
            return range($self->start,$self->end);
        };

    }

I’ve defined the static methods in the usual way, non-JavaScript style. And there is, of course, the mandatory __call() method.

class PageRange...

    public function __call($method,$args) {
        return call_user_func_array($this->$method,$args);
    }

    public function getStart() { return $this->start; }

    public function getEnd() { return $this->end; }

    public function getLength() { return $this->length; }

    private static function calculateEnd($start,$length) {
        return $start + $length - 1;
    }

    private static function calculateStart($end,$length) {
        return $end - $length + 1;
    }

    private static function calculateLength($start,$end) {
        return $end - $start + 1;
    }

    public static function withStartAndLength(
        $start,$length)
    {
        return new self(
            $start,
            self::calculateEnd($start,$length),
            $length
        );
    }

    public static function withEndAndLength($end,$length) {
        return new self(
            self::calculateStart($end,$length),
            $end,
            $length
        );
    }

    public static function withStartAndEnd($start,$end) {
        return new self(
            $start,
            $end,
            self::calculateLength($start,$end)
        );
    }

}

An interesting aspect of this class is the fact that the constructor is private, so you have to use one of the creation methods. That’s part of my variation on the range pattern.

Martin Fowler puts it this way:

Technical Debt is a wonderful metaphor developed by Ward Cunningham to help us think about this problem. In this metaphor, doing things the quick and dirty way sets us up with a technical debt, which is similar to a financial debt. Like a financial debt, the technical debt incurs interest payments, which come in the form of the extra effort that we have to do in future development because of the quick and dirty design choice. We can choose to continue paying the interest, or we can pay down the principal by refactoring the quick and dirty design into the better design. Although it costs to pay down the principal, we gain by reduced interest payments in the future.

Brandon’s argument in favor of commenting is perfectly valid, but misses the crux of the matter, since he ignores the option of actually improving the code itself rather than just adding comments.

Let me also comment briefly on Marco Tabini’s reponse:

What I suspect Brandon really means is that the comments are there to illustrate the intentions of the author when those intentions are not immediately made obvious by the code itself.

Yes. And no. There is no absolute boundary, no limit in principle, to how intention-revealing code can be. It’s not necessarily easy in practice, though. As I’ve said before, it’s primarily inline comments that I’m objecting to. The comments I feel a need to write are often at the class level and address the interaction between different classes.

Anyway, arguing about it theoretically is not the way to resolve the issue. Show me some good examples of comments that serve to make code clearer and that supposedly can’t be usefully eliminated by refactoring the code into something more readable. I’ll either admit that you’re right or show you (or at least outline) how to do it differently. I do recognize that even inline comments are useful…occasionally.

(By the way, I seem to have missed Brandon’s comment (Where Comments Are Useful) to my comments considered harmful post last December.)

I discovered a video presentation available from QCon SF 2008 by Neal Ford called 10 Ways to Improve Your Code. Although the examples are in Java, most of the presentation is relevant to PHP. There are some ideas here that I’ve never heard of myself, such as “anti-objects”.

Some of the main headings are a bit cryptic, so you may have to see the video itself to have them explained.

Here are the 10 ways:

1. Composed method
2. TDD (test-driven development/design)
3. Static analysis
4. Good citizenship
5. YAGNI (you ain’t gonna need it)
6. Question authority
7. SLAP (single level of abstraction principle)
8. Polyglot programming
9. Every nuance (=learn every nuance of your programming language)
10. Anti-objects

I recommend this presentation. It’s about the things that really matter if you want to be productive.

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.

After I did my own research, I discovered that someone had beat me to it. As early as September last year Fredrik Holmström wrote about Javascript-OO & Python-DuckTyping in PHP5.3.

I’ve done the same thing independently and somewhat differently, so it’s interesting to compare. Unlike Holmström, I’m defining the closures inside the constructor for the class that’s using them. That makes the code that uses the class a little more similar to what we’re used to.

Let’s start with a “Hello world” example.

class HelloWorldWithClosures {
    private $hello;
    private $goodbye;

    public function __construct() {
        // If we try using $this inside the closure, we get a syntax error.
        // So we need another variable name, which is basically arbitrary.
        $self = $this;

        // $self is not actually used inside this method/closure, but we want to be consistent.
        $this->hello = function() use ($self) {
            echo "hello world...\n";
        };

        $this->goodbye = function() use ($self) {
            $self->hello();
            echo "...and goodbye for now\n";
        };
    }

    public function __call($method,$args) {
        return call_user_func_array($this->$method,$args);
    }
}

The closures are instance variables in the class, and the __call() method is set up to call the correct closure when calling the method in the usual way in PHP.

Now we can call a plain method that uses nothing else from the class:

$obj = new HelloWorldWithClosures;
$obj->hello(); // prints "hello world..."

And we can call the goodbye() method that starts by calling hello():

$obj = new HelloWorldWithClosures;
$obj->goodbye();
// prints "hello world...
//...and goodbye for now"

We can also add new methods to object that’s already instantiated without changing the class:

$obj->helloAgain = function() use($obj) {
    $obj->goodbye();
    echo "...and hello again\n";
};

This last example exploits the somewhat vulgar fact that you can still add public instance variables on the fly to an object, as in PHP 4.

A different approach that avoids this, but is a bit more verbose, would be to use an array to store the closures in the object:

class HelloWorldWithClosures2 {
    public $methods = array();

    public function __construct() {
        $self = $this;

        $this->methods['hello'] = function() use ($self) {
            echo "hello world...\n";
        };

        $this->methods['goodbye'] = function() use ($self) {
            $self->hello();
            echo "...and goodbye for now\n";
        };
    }

    public function __call($method,$args) {
        return call_user_func_array($this->methods[$method],$args);
    }
}

In addition, we would normally need to throw an execption when a method does not exist. The blog post I linked to at the beginning has this feature.

Those are the basics of how to write JavaScript-classes in PHP 5.3. Whether you actually want do it this way depends on your needs. There’s no point unless you actually want to use the flexibility this style of programmer affords.

At the PHP UK conference, I saw Sebastian Bergmann’s presentation on lambda functions, closures and traits. Lambda functions and closures are scheduled for 5.3 (or fivethree, as I’ve affectionately named the binary), or later. The presentation was intriguing, but has only simplistic examples, sufficient to illustrate the mechanical aspects. It left me curious as to what these features could be used for in real programs.

Before we start playing, let’s get the basic terminology clear. Lambda functions and closures are two fancy names for (variations on) anonymous functions. These are functions that are more flexible than ordinary functions and can be stored in variables or defined just where they are needed.

Anonymous functions are possible even in pre-5.3 PHP. They can be created using create_function(). But this is cumbersome, ugly, error-prone and possibly insecure. PHP 5.3 lets you do this in a much more natural and pleasant way.

The most basic and obvious case is sorting. Here is an example from Sebastian’s presentation:

<?php

usort(
    $list,
    function ($a, $b) {
        if ($a == $b) return 0;
        return ($a < $b) ? -1 : 1;
    }
);

In PHP before 5.3, this must be done either by using create_function() or by defining the function somewhere else, away from where it’s actually used. The above is clearly much better.

What else can we do with anonymous functions? In Ruby, they are the standard way of processing arrays. For example, if we want to process a set of files, adding a directory name at the beginning, we can do this:

files = ['pdo.a','pdo.la','pdo.so','sqlite.a','sqlite.la','sqlite.so'];
files_with_dir = files. map  { |f| "modules/#{f}" }

The snippet inside the braces is a function. map is the Ruby equivalent of PHP’s array_map(), except that Ruby is built to do this particular trick. But let’s try the equivalent with PHP 5.3. First we define the array:

$files = array('pdo.a','pdo.la','pdo.so','sqlite.a','sqlite.la','sqlite.so');

And then we process it:

$filesWithDir = array_map(
    function($f) { return "modules/$f" ; },
    $files
);

Interesting, but not necessarily better than the conventional alternative:

$filesWithDir = array();
foreach ($files as $file) {
    $filesWithDir[] = "modules/$file";
}

Using array_map() seems like a realistic option, at least for some cases. It reads differently because it’s conceptually different, focusing on processing the entire array rather than one element at a time. You might find it cleaner. And in some cases, it will be clearly superior. If you have a slightly more complex structure than a simple one-dimensional array, you can use array_map_recursive() to simplify the code dramatically.

In part 2, I’ll present an example of a JavaScript-style class composed of closures.

The debate on the “one assertion” principle continues. Pádraic Brady and I agree on the general principle, but since he is so categorical in his second article, I needed to inspect his reasoning more closely. It’s clear that our disagreement is more than superficial. The more I think about it, the more I disagree.

The state of the art

Pádraic maintains that one assertion per test is a rule that should always be followed unless there is a specific good reason to break it. I prefer it as a guideline, as does Robert C. Martin in the book Clean Code. The reference is not intended as an appeal to authority to “prove” that I’m right. I’m just making the point that I think this reflects the current state of the art, which is not necessarily perfect, of course.

How small is a behavior?

So what is the basis for wanting to enforce this principle as a strict rule? Pádraic claims that “1 behavior == 1 assertion”.

How does that make sense? The starting point is Behavior-Driven Development (BDD). I agree with the BDD principle that one test should test one behavior—as a guideline. It’s makes tests more focused, more readable and makes for better error messages when tests fail. Above all, it forces you to think about what is a behavior and what is not. And the idea of one assertion per test drives that thinking process.

From that point of view, “1 behavior == 1 assertion” seems totally logical. Unfortunately, it misses the point. It introduces a mechanical equivalence that negates the very thinking process I was just advocating. It makes the conceptual notion of a single, atomic behavior dependent on syntax and on the implementation specifics of a test framework.

For example, let’s say we want to test that a product object represents a certain model, a Logitech Harmony One remote control.

$this->assertEquals('Logitech', $product->make);
$this->assertEquals('Harmony One', $product->model);

It’s two assertions, but we’re only testing for one thing. We just want to make sure this product is what it should be and not something else. But let’s think some more about it. There are several ways we could make this into one assertion instead of two. This one, for instance:

$this->assertTrue(
'Logitech' == $product->make  &&  'Harmony One' == $product->model);

Not very pretty, is it? I think we can agree that this is not an improvement. More importantly, it doesn’t change the nature of what we are testing. We didn’t change what we’re testing, we just changed the way we express the test. A better way to get one assertion would be to make a custom assertion method such as assertLogitechHarmonyOne(). That would be more readable, but it wouldn’t help our statistics. The test framework would still see two assertions and report this as a 1 to 2 relationship between tests and assertions. And again, what we’re testing remains the same.

It gets worse. We’re testing one thing, but are we testing one behavior? No, we’re just testing the outcome. This is another logical flaw in the “1 behavior == 1 assertion” equivalence. A behavior is not tested by assertions, it’s tested by a complete test method. What happens before the assertions also counts, obviously. You could have multiple behaviors in the test with a single outcome that could be tested by a single assertion.

But I haven’t mentioned the simplest way to get one assertion per test. Just delete all assertions but one. It’s cheating, and problably toxic the quality of your tests, but it satisfies the criterion and generates good-looking statistics. It’s the thing that’s bound to happen if you try to force this on developers.

Better not use the “one assertion” principle as a strait jacket. It works better as exercise equipment to jog your mind.

Pádraic Brady pleads for the principle that a unit test method should have only one assertion. His point is perfectly valid; there are several good reasons why one assertion per method is a smart guideline when writing unit tests. But since he drags up the term “lazy”, I feel the need for soul-searching and confession.

The average for my current unit tests still hovers around three or four assertions per test method. And when I think about it, I see that the reason is that I’m not always taking the time to practice “one assertion per test” as a strict rule. Instead, it’s part of my problem-solving strategy when I start to get confused by my own tests; when the tests get so complex that I can’t quickly understand what’s going on where. Mock objects, in particular, contribute to this, since mock expectations specify what should happen later instead of testing what’s already happened.

Anyway, when I encounter this problem, known unsurprisingly as Complex Test or Obscure test, my first impulse is to make sure the code I’m testing (known as the system under test or SUT) is not too complex. Classes that are too large and methods that are too long are my prime examples of code that’s hard to test in a simple way. After I check the SUT, I look at the tests, and yes, then one of my goals is to move toward the “one assertion” ideal. It really is helpful at that point.

I’m open to the possibility that I should be more consistent in applying this principle. He may be right that there is a danger of “lazy/shallow testing”. In any case, as with all code, bugs and deficiencies are easier to spot the more readable it is.

As Kevlin Henney pointed out at the PHP UK Conference 2007, PHP type hints are not hints.
Rather, they are instructions to PHP to check the type. That may not be terribly important,
but it’s worth pointing out, since confusing terminology is less confusing if you understand how it’s confusing.

Anyway, I hereby apologize to the gods of programming for using the term and for the fact that I intend to keep on using it.