All Articles | implements Elegance { // Elwyn Malethan's Blog

Zed Shaw: There Are No Famous Programmers

2010-06-09T13:13:45Z

[T]oday I was offered a system administrator job, again. It was very humbling to say the least. It kind of knocked me out to have someone think through all the things their company needs and the only thing they could think I'd be good at was system administration.

Yep, just a system administrator. Still.

I still have to do programmer interviews like everyone else. No matter how much code I put out, I still have to solve stupid puzzles about coconuts and manholes. No matter how many web servers or email frameworks or database servers or chat servers or assemblers I write I still have to prove I can code. No matter how many copies of my software get deployed I still have to prove I can make reliable software..

If, with his obvious achievements. Zed Shaw gets mistaken for someone to do sysadmin work, maybe much less accomplished guys like me should just give up.

Having said that, what‘s the alternative?

Comments have no place in code

2010-05-19T19:10:22Z

The view I have developed about code comments is informed by years at the coal face of software development and re-enforced by what @unclebobmartin has to say about them in Clean Code, which I read last year and continue to refer back to.

Stale comments lie.

In my opinion, commenting code is the laziest way of expressing intention or semantics in code. Why? Because comments are not code. They are not an integral part of the running program. They are not bound by syntax or verified by unit testing.

This wouldn‘t be so bad if that code were never subsequently to be changed. Code is always changing. As agilists we‘re always tweaking and refactoring our code to reflect new or changing requirements. It‘s all part of embracing change. There is therefore nothing (beyond attentive human inspection) to prevent comments from becoming stale, detached or irrelevant. Stale, detached or irrelevant comments are worse than no comments. Opaque code with no comments merely obfuscates, opaque code with stale comments lies.

So what‘s the alternative? It is is more–or–less accepted wisdom now that if it is unclear what some code does (or at least what is intended) by reading it then it should be refactored so that it is clear, elegant and expressive. Rename methods, extract unclear code into new methods and classes, reduce responsibilities.

This is all expressed more elegantly and in far more detail by Bob Martin in Clean Code and countless other books and articles that predate it.

What about the ‘why‘

Jeff Atwood has already contributed his tuppence worth on this subject and I agree with a lot of he says. Apart one from one thing, he says that comments have a legitimate role in describing to the reader the reasoning behind decisions to implement a solution in a given way. I agree with him that it is difficult to express this information in code alone and that an additional enrichment of the code is required. I think he‘s wrong to say that comments are the best way to achieve this.

Version history and meaningful commit messages can better and more reliably express the reasons behind decisions made. I do this all the time in my day to day coding. If I see some code that I fail to understand the reasoning behind I look up the history of the file and read the commit messages. The code base I‘m currently working with has undergone a lot of change and few of the many comments that litter the code are of any use. Luckily, there is a wealth of information in the Subversion commits, some with references to issues in JIRA.

The commit messages are persistent and reliably associated with lines of code. They don‘t become stale and they don‘t become detached from their context.

Ugly

So there it is. Code comments are bad, they‘re ugly and they create more trouble than their worth.

More than anything, it‘s the ugliness I take most issue with.

If you‘re into software craftsmanship, then you‘re interested in elegant and (dare I say it) beautiful code. You‘re interested in code that tells a story, that expresses to the reader your intention. Essentially, this is code that documents itself. This sort of code does not need comments.

Hardtail to FS: A disconcerting journey

2010-04-29T15:24:16Z

After years of riding a hardtail I recently bought myself a full-supsension bike. It‘s a 2005 Cannondale Prophet with 140mm travel, provided by a Lefty on the front and a Manitou 3-way Swinger on the back. It was hardly used, not a single scratch or any sign of wear, when I got it and I have to say I couldn't be happier with the bike. Already it almost feels as familiar as my hard-tail of 8 years, a 2002 Kona Caldera with 100mm Fox Vanilla on the front.

As happy as I am with my new FS bike, a few niggling doubts have crept into my mind about the benefits of riding a bike that bends in the middle.

Laziness

When riding a hard-tail, I‘m always carefully choosing a line. I‘m choosing a line that will maintain speed, set me up for the right line further down the track and most of all I‘m choosing a line that will not completely kill the rear of my bike. This is even more of a consideration when climbing because in order to keep the power down the back needs to be touching the trail.

On the Prophet, I can be far less picky about the terrain I decide to ride over. This seems good to start with, it feels liberating not to have to worry about the kind of bumps and drops that would make life on a hard-tail positively uncomfortable. But now, because I can give less consideration to minor undulations in the trail, I kind of feel I‘m losing some sharpness, losing focus, losing precision. I don‘t feel like I‘m learning anything new when I go out on the trail. I‘m still new to the Prophet and FS in general. Maybe these things will come back as – over time – I gain confidence and therefore speed.

Raising the stakes

Speed. Everything can be so much faster with a bike that bounces both ends. Again, I initially reveled in the capability to go faster on the Prophet over terrain that I know I would have to hold back on with the Caldera. A graze-inducing stack and a few sphincter tightening near misses a couple of weeks ago at the Marin Trail at Gwydyr Forest is bringing into sharp focus how, with that extra freedom, comes higher stakes. It‘s making me think about things like body armour and full face helmets. These are not comfortable thoughts to be having.

I‘ll be riding the Dyfi Enduro this weekend (2nd May 2010). I‘ve never done it before, though I have ridden some of the route on a different ride.

So will I be taking the Caldera? Hell no, the Prophet is way, way more fun!

Unit testing with Commons HttpClient

2010-04-26T15:42:07Z

I‘ve been adding some test coverage to some existing code today. This code under test uses Commons HTTP Client to fetch data from an external resource. I ran into problems with mocking/stubbing the response to the HTTP requests.

I am not the only one who has faced problems with this Http Client. In that article, Florin provides a good solution using a concrete subclass of HttpClient in order to mock it‘s behaviour. His article was very useful in helping me formulate my approach.

I use JMock for dynamic mock objects and so I was keen not to have to mix of JMock-based mocks and concrete mock objects. So my approach is to use JMock‘s custom actions to provide an implementation that populates the right values in the right way. Although, I had to use some reflective cheating to set the necessary values.

private static Action willRespondWith(final int code, final String status, final String body) {
    return new CustomAction("will respond with status: " + code +  ", and contents: " + body) {
        @Override
        public Object invoke(Invocation invocation) throws Throwable {
            final Object method = invocation.getParameter(0);

            final Field statusLine = HttpMethodBase.class.getDeclaredField("statusLine");
            statusLine.setAccessible(true);
            statusLine.set(method, new StatusLine("HTTP/1.0 " + code + " " + status)); //Although, 'OK' could be anything

            final Method setResponseStream = HttpMethodBase.class.getDeclaredMethod("setResponseStream", InputStream.class);
            setResponseStream.setAccessible(true);
            setResponseStream.invoke(method, new ByteArrayInputStream(body.getBytes("UTF-8")));

            return code;
        }
    };
}

This is intended to be used as follows:

@Test
public void testSomeHttpStuff() throws Exception {

    jmock.checking(new Expectations() {{
        allowing(client).executeMethod(with(any(HttpMethod.class)));
        will(willRespondWith(200, "OK", "{some: 'value'}"));
    }});

    sendHttpRequest("http://some.server/some/resource.json");

}

Now I can simulate all sorts of responses from the external resource.

Snowed-on Snowdon

2010-03-08T21:59:51Z

The view of Llanberis and Snowdon from Fachwen. March 2010.

If the users aren't motivated to help with software development...

2010-02-24T15:19:09Z

If the users aren't motivated to help with software development by answering questions or reviewing the results of a sprint, then the software isn't creating any value. Stop work now and find something the users really want. — Stephen Lott

The number of times I‘ve wanted to do that! Some customers I‘ve worked with are really averse to engaging in the development process. However, it makes those customers that do eagerly engage in the process all the more a delight to work with. Guess which customers had most success with their projects…

JavaScript BDD framework in less than 200 lines

2010-01-24T17:52:02Z

I‘ve been doing a lot of work with JavaScript lately and so I‘ve been thinking a lot about how to effectively bring my experiences of BDD and TDD in other technologies to the party. There are a few test frameworks available, JsTestDriver by far the better looking of the lot. There is a specification framework, based on rspec as well. However, I couldn't find a JavaScript BDD story framework anywhere. So armed with some new knowledge from JavaScript: The Good Parts, I had a go at looking into what such a framework would look like. I was surprised as to how quickly I came up with a solution and how small the footprint of the end result is.

So here it is, in less than 200 lines, a JavaScript BDD Framework I've called it BehaviourJS and I've made it available under the GNU Lesser General Public License.

// ------------------------------------------------------------ Function augmentation

/**
* Standard means of augmenting everything with new methods
*
* @param name the name of the new method
* @param func the function we want invoked
*/
Object.prototype.method = function(name, func) {
    if (!this.prototype[name]) {
        this.prototype[name] = func;
        return this;
    }
};

// ------------------------------------------------------------ Should DSL

behaviourJs = {};

behaviourJs._shouldBe = function(expected) {
    if(expected !== null) {
        var exp = expected.valueOf();
        var self = this.valueOf();
        if(self === exp) {
            return;
        }
    }
    throw {
        name: 'AssertionError',
        message: 'Expected ' + expected + ' but was ' + this
    };
};

Object.method('shouldBe', behaviourJs._shouldBe);
Object.method('shouldEqual', behaviourJs._shouldBe);
Object.method('shouldBeEqual', behaviourJs._shouldBe);
Object.method('shouldBeEqualTo', behaviourJs._shouldBe);

behaviourJs._shouldNotBe = function(expected) {
    if(expected !== null) {
        var exp = expected.valueOf();
        var self = this.valueOf();
        if (self !== exp) {
            return;
        }
        throw {
            name: 'AssertionError',
            message: 'Expected not to be ' + expected + ' but was ' + this
        };
    }
};

Object.method('shouldNotBe', behaviourJs._shouldNotBe);
Object.method('shouldNotEqual', behaviourJs._shouldNotBe);
Object.method('shouldntBe', behaviourJs._shouldNotBe);
Object.method('shouldntEqual', behaviourJs._shouldNotBe);

// ------------------------------------------------------------ StoryInstance

behaviourJs.StoryInstance = function(block) {
    block.call(this);
};

behaviourJs.StoryInstance.prototype.visit = function(visitor) {
    visitor.visitStory(this);
};

behaviourJs.StoryInstance.prototype.run = function() {
    this.visit(new behaviourJs.StoryRunner());
};

// ------------------------------------------------------------ ScenarioInstance

/**
* A runnable scenario.
*
* @param name the description of the scenario
* @param block the function containing the contents of the scenario (usually
* a series of Givens,When and Thens).
*/
behaviourJs.ScenarioInstance = function(name, block) {
    this.name = name;
    this._steps = [];

    behaviourJs.ScenarioInstance.__currentScenario = this;

    block.call();

    behaviourJs.ScenarioInstance.__currentScenario = null;
    behaviourJs.ScenarioInstance.__currentPhase = null;
};

behaviourJs.ScenarioInstance.__currentScenario = null;

behaviourJs.ScenarioInstance.__currentPhase = null;

behaviourJs.ScenarioInstance.prototype.addStep = function(step) {
    this._steps[this._steps.length] = step;
};

behaviourJs.ScenarioInstance.prototype.visit = function(visitor) {
    visitor.visitScenario(this);
};

// ------------------------------------------------------------ Step

behaviourJs.Step = function(type, meta, block) {
    this._type = type;
    this._meta = meta;
    this._block = block;
};

behaviourJs.Step.prototype.visit = function(visitor) {
    visitor.visitStep(this);
};

// ------------------------------------------------------------ StoryRunner

behaviourJs.StoryRunner = function() {
    this.storyCtx = {};
};

behaviourJs.StoryRunner.prototype.visitStory = function(story) {
    var title = 'Story: ' + story.description;
    document.writeln(title);
    var line = '';
    for(var i = 0; i < title.length; ++i) {
        line += '=';
    }
    document.writeln(line);
    for (var scenIndex = 0; scenIndex < story.scenarios.length; ++scenIndex) {
        story.scenarios[scenIndex].visit(this);
    }
};

behaviourJs.StoryRunner.prototype.visitScenario = function(scenario) {
    document.writeln('Scenario: ' + scenario.name);
    for (var stepIndex = 0; stepIndex < scenario._steps.length; ++stepIndex) {
        var step = scenario._steps[stepIndex];
        step.visit(this);
    }
    document.write("\n");
};

behaviourJs.StoryRunner.prototype.visitStep = function(step) {
    var stepDesc = step._type.toUpperCase() + ' ' + step._meta;
    if (step._block === undefined || step._block === null) {
        if (step._type === 'then') {
            stepDesc += ' [PENDING]';
        }
    } else {
        try {
            step._block.call(this.storyCtx);
        } catch(e) {
            if (e.name == 'AssertionError') {
                stepDesc += ' [FAIL : ' + e.message + ']';
            } else {
                stepDesc += ' [ERROR (' + e.name + ') : ' + e.message + ']';
            }
        }
    }
    document.writeln(stepDesc);
};

// ------------------------------------------------------------ DSL

Story = function(block) {
    return new behaviourJs.StoryInstance(block);
};

Scenario = function(name, block) {
    return new behaviourJs.ScenarioInstance(name, block);
};

Given = function(desc, block) {
    var scenario = behaviourJs.ScenarioInstance.__currentScenario;
    behaviourJs.ScenarioInstance.__currentPhase = 'given';

    scenario.addStep(new behaviourJs.Step(behaviourJs.ScenarioInstance.__currentPhase, desc, block));
};

When = function(desc, block) {
    var scenario = behaviourJs.ScenarioInstance.__currentScenario;
    behaviourJs.ScenarioInstance.__currentPhase = 'when';

    scenario.addStep(new behaviourJs.Step(behaviourJs.ScenarioInstance.__currentPhase, desc, block));
};

Then = function(desc, block) {
    var scenario = behaviourJs.ScenarioInstance.__currentScenario;
    behaviourJs.ScenarioInstance.__currentPhase = 'then';

    scenario.addStep(new behaviourJs.Step(behaviourJs.ScenarioInstance.__currentPhase, desc, block));
};

And = function(desc, block) {
    var scenario = behaviourJs.ScenarioInstance.__currentScenario;
    scenario.addStep(new behaviourJs.Step(behaviourJs.ScenarioInstance.__currentPhase, desc, block));
};

My approach is heavily influenced by my experiences of using Easyb for BDD for Java. There are a few things I haven‘t added, such as before and after hooks.

Stacktrace support in JavaScript is sketchy and differs greatly across runtimes/browsers. One solution might be to integrate this attempt at universally obtaining a stacktrace. The should DSL is not as comprehensive as Easyb. Unlike Easyb the should DSL in BehaviourJS is completely extensible. This is possible because of the nature of the JavaScript langauge.

I mentioned runtimes/browsers earlier. The other potential issue is that I have only tested this in Firefox. It‘s the product of a couple of hours hacking so it‘ll be no surprise if it fails in other browsers.

Runners, build system and IDE support.

I realise that just implementing such a framework isn‘t even half of the effort required for a test framework to enable developers to practice TDD or BDD. For this framework to be useful to me or anyone else, it will need IDE support (IDEA and Eclipse at least) and build system support (Maven and maybe Ant).

The existing JavaScript test frameworks have had a lot of work put into this area and it shows. Especially with JsTestDriver‘s IDE support, which is awesome.

Maybe next weekend I‘ll have a look at plugin this into an existing test framework, such as JsTestDriver.

Example story

A story using the above framework might look something like this.

Story(function() {
    this.description = "This is an example story";
    this.summary = {
        as_a : "role",
        i_want : "to perform some action",
        so_that : "there is some perceived benefit"
    };

    this.scenarios = [
        Scenario("Some scenario", function() {
            Given("some string", function() {
                this.someString = 'this';
            });
            And("some number", function() {
                this.ten = 10;
            });
            When("something happens");
            Then("some condition is evaluated", function() {
                this.someString.shouldNotBe(null);
                this.someString.shouldNotBe({});
                this.someString.shouldNotBe(123);
                this.someString.shouldNotBe('that');

                this.someString.shouldBe(this.someString);
                this.someString.shouldBe('this');
            });
            And("some other condition is evaluated", function () {
                this.ten.shouldBe(10);
            });
        }),
        Scenario("Checking incorect values", function() {
            Given("some new precondition");
            And("some other new precondition");
            When("something new happens", function() {
                this.animal = 'animal';
            });
            Then("some new condition is evaluated", function() {
                try {
                    thisVar.doesNotExist();
                } catch(e) {
                    // gulp
                }
            });
            And("some other new condition is evaluated", function() {
                try {
                    this.animal.shouldBe('farm');
                } catch(e) {
                    e.name.shouldBe('AssertionError');
                }
            });
        }),
        Scenario('some complex objects', function() {
            Given(' a complex object', function() {
                this.MyThing = function(val) {
                    this._val = val;
                };

                this.someObj = new this.MyThing('a value');
            });
            And('a copy of it', function() {
                this.sameObj = this.someObj;
            });
            And('a different object', function() {
                this.differentObj = new this.MyThing('a value');
            });
            Then('the object and the copy should be the equal', function() {
                this.someObj.shouldBe(this.sameObj);
                this.sameObj.shouldBe(this.someObj);
            });
            And('the object and the different one should not', function() {
                this.someObj.shouldNotBe(this.differentObj);
                this.differentObj.shouldNotBe(this.someObj);
            });
        })
    ];
}).run();

The link to JavaScript: The Good Parts above is an affiliate link. It's a great book, written by a programmer for programmers.

GP Practice Design looks familiar

2010-01-11T18:41:40Z

This ...

... looks an awful lot like this...

... wouldn‘t you say?

Is this plagiarism? Decide for yourself?

Why TDD: Freedom to refactor

2010-01-10T12:08:18Z

Dave and Jen work for software companies that produce exciting and clever software products. Both Dave and Jen understand design patterns. They both know about encapsulation, inheritance, composition and all that jazz. They‘re both good software developers. The only difference is that Jen has taught herself to develop test-driven. Dave thinks his time is better spent writing production code.

Dave and Jen started their current project at the same time. Dave spent some time up–front to carefully design his architecture to the requirements and implemented all the features. Dave added some unit tests, but only as an afterthought. Dave is confident that his architecture is well suited to providing a maintainable solution to the requirements specified. Dave is OK with the fact he has less than 25% test coverage.

Jen used TDD, she started off by adding some tests to represent some of the requirements and implementing production code to pass those tests. She did this iteratively and in small digestible chunks until she had satisfied all of the requirements. Jen changed the architecture of the project frequently. She refactored as she went, renaming classes and methods so that they better represented their function, moving code and responsibilities between classes to continually improve the design of the software. She did this safe in the knowledge that her tests would pick up any errors introduced. Jen builds up test coverage of over 80%.

As always happens in a software project, the requirements change. In Dave‘s case, management decided that – for political reasons – Dave needed to completely change the way his product worked. Jen‘s customer‘s priorities changed. To stay competitive, they needed to have different features. In both cases – as ever – time was short and deadlines were tight.

Both Jen and Dave found that their existing design wasn‘t really suited to the new requirements. Dave was concerned about the deadline and the time it would take to evaluate the correctness of any change he made in the design of the software. He has no timely or repeatable means of doing this. So Dave added the feature without changing the design. He knew it wasn‘t ideal and that the he would need to change the architecture at some point in the future. Given the time constraints, Dave believed he was being pragmatic.

Jen – on the other hand – had been refactoring the code extensively throughout the development of the project. Jen recognises an alternative design that would elegantly accommodate this new requirement and refactors. She runs the tests to see if she broke something. A few of them fail. So she fixes them and runs the tests again, safe in the knowledge that her tests represent the requirements.

Over the next few years a number of new features are requested by both Dave‘s and Jen‘s customer(s). Each time, Dave opts for the change that least affects the existing code-base. Each time Dave‘ project becomes more like a ball of mud. Dave becomes more and more resistant to new features. He started asking management for some “engineering time“ to refactor the code and have the time to evaluate it‘s correctness. This – he knew – would take some time.

In the same time, Jen‘s team have been doing nothing but implementing new features. The design of the software has changed frequently in that time. She doesn‘t need any “engineering time”, her tests evaluate the correctness of every feature she adds.

Dave has become scared of changing the code, he doesn‘t know what he might break.

Jen breaks the code every day. She‘ll know in seconds what she‘s broken and what she needs to do to fix it.

The design patterns link above is an affiliate link. Any and every software developer should have a well–thumbed copy of this book.

TDD in JavaScript intensive software

2010-01-05T18:15:18Z

I recently switched jobs. I left Smartstream for somewhere closer to home. I did this primarily to avoid the commute from Cardiff to Aztec West, in Bristol. I'll be glad to avoid that drive on the M4 every day. I joined Move, who are based in Utah but have a development office not too far from Cardiff.

Having been working in the familiar world of server–side Java before Christmas, I‘ve now moved to the team that work on what we call the “middleware”. Primarily, this is the client software that runs on set–top boxes or web browsers. This is therefore almost entirely JavaScript.

Developing software that is primarily JavaScript is a new experience for me and one I‘m relishing, if with some trepidation. After a bit of Googling, I‘ve basically concluded that there isn‘t vast support for TDD for JavaScript development. This is especially true of IDE support. One thing that does look promising is JsTestDriver, though I‘ve been having trouble getting it to work reliably. This is most likely lack of familiarity with both JavaScript and JsTestDriver.

This is challenging stuff, but that‘s great as far as I‘m concerned.