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.

Brandon Savage is writing a series on code improvement using a code example (starting with Peer Review: Taking Code And Making It Better). In other words, it’s about refactoring, which is practically my favorite subject. Although I don’t agree with all of it, it’s mostly good advice. I recommend it.

That said, I do have something important to add. The series is missing the first, most basic rule: Don’t refactor unless you have good automated test coverage (typically with unit tests). And if there are no test, write them before you start refactoring. If you don’t, you’ll make mistakes and get lost in a frustrating bug search, unless you’re very stingy and don’t refactor too much. With test coverage, you have freedom to experiment, to change something and change it back if you don’t like the result. This, above all, is what makes refactoring such a great learning experience.

Some of those who have commented on the post Peer Review: Looking Into Abstraction (Greg Beaver, Jeff Carouth) mention testing and point out the need to inject objects so that they can be replaced with mock objects for testing. This is a wise move, and practically unavoidable in this case. To support refactoring, unit tests need to be run frequently, without accessing outside services (twitter or email in this case) that take time to process.

This means that in this case, it’s actually necessary to refactor a bit before proper unit tests can be implemented. This is what Michael Feathers calls the Legacy Code Dilemma in his book Working Effectively with Legacy Code. Certainly building this dilemma into new code is not a good idea. Make the code unit-testable before it’s too late.

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.

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.

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