chris clarke

Ignoring Common Coding Practice (why you should be too)

chris.probably — Fri, 04 Apr 2008 00:13:48 +0000

Simon Baker wrote a quick blog entry on Common Sense and Common Practice. It hit home with me because recently I’ve been pairing with developers who find it uncomfortable coding in certain ways because it doesn’t fit with Common Practice. A lot of code I see, whether it be reading a programming book, looking at some code I Googled, or looking back at the way I was taught at University, is really just a bit rubbish in my opinion. It works okay, and I’m sure a computer can understand it, but as a human I find myself struggling a bit. Typically the code seems to be telling me how the computation is taking place rather than what it is doing. Sure, you need some how code but put it behind a little what code and give me a chance.

Anyway, enough passive-aggressive blogging, here are some things that people tend to find uncomfortable and perhaps why they shouldn’t:

Long names

    @Test public void findingXMLElementByNameThrowsExceptionWhenElementDoesNotExist() {

        String someXmlWithNoFrankTag = "...";

        Document xmlDocument = XmlUtils.toDocument(someXmlWithNoFrankTag);

        try {

            XmlUtils.findElementByName(xmlDocument, "frank");

            fail("Expected exception to be thrown because the element 'frank' does not exist!");

        } catch (JDOMException expectedBecauseElementShouldNotBeFound) {

        }

    }

Long descriptive names seem uncomfortable to people because you don’t normally see them in Common Practice. I think they help because it’s much easier to see what’s going on without looking in to the details of the languages implementation and its easier to find code that already does what you want.

Extracting composed methods that don’t remove duplication

Before:

public void somebodyCheckedIn(CheckIn checkIn) {

    for (CheckIn checkIn : codeCheckIns) {

        if ("christopherc".equals(checkIn.committer())) {

            // update web page

            page.printTitle("Code changed by: "   checkIn.committer());

            page.printHeader("On date: "   checkIn.date());

            page.printBold("Changes: ");

            for (CodeChange codeChange : checkIn.codeChanges()) {

                page.print("File "   codeChange.fileName()   ": ");

                page.print("Diff: "   PrettyDiffFormatter.format(codeChange.diff()));

            }

            // kick off build

            if (builder.isRunning()) {

                builder.stop();

                builder.reset();

            }

            builder.emptyBuildQueue();

            builder.addToBuildQueue(new Build(checkIn));

        }

}

}

After:

public void somebodyCheckedIn(CheckIn checkIn) {

    for (CheckIn checkIn : codeCheckIns) {

        if ("christopherc".equals(checkIn.committer())) {

            updateWebPageWithCheckIn(checkIn);

            stopTheBuildIfItsRunningAndBuild(checkIn);

        }

    }

}

private void updateWebPageWithCheckIn(CheckIn checkIn) {

    page.printTitle("Code changed by: "   checkIn.committer());

    page.printHeader("On date: "   checkIn.date());

    page.printBold("Changes: ");

    for (CodeChange codeChange : checkIn.codeChanges()) {

        page.print("File "   codeChange.fileName()   ": ");

        page.print("Diff: "   PrettyDiffFormatter.format(codeChange.diff()));

    }

}

private void stopTheBuildIfItsRunningAndBuild(CheckIn checkIn) {

        if (builder.isRunning()) {

            builder.stop();

            builder.reset();

        }

        builder.emptyBuildQueue();

        builder.addToBuildQueue(new Build(checkIn));

}

People seem a bit uncomfortable with this refactoring because they think it doesn’t achieve anything except adding more code. Sure, no duplication has been removed but its now much clearer what the public method does without having to look in to the imperative details of how it does it in the private methods. I can now understand this code at a glance after splitting out the two things that were happening inside the loop and as an added benefit I was able to remove some comments by naming the methods well.

Creating classes to express your domain

Ivan Moore and Keith Braithwaite ran a workshop at SPA 2008 on Programming as if the domain mattered which inspired me on this one.

For example, if you are writing a Banking application, you can create classes that express familiar language in Banking.

Without domain classes:

    String customer = "Mr Clarke";

    long custId = 234234555;

    double amount = 500.0;

    double interest = 1.055;

    Account account = new Account(customer, custId, null, null, 0.0);

    account.open();

    account.setAmount(amount * interest);

    database.save(account);

With domain classes:

    Customer customer = new Customer("Mr Clarke", 234234555);

    Money money = new Money(500.0);

    Interest interest = new Interest(5.5);

    Account account = customer.openAccount(money);

    account.addInterest(interest);

    database.save(account);

I’ve found people are put off by this domain language because a lot of the classes involved don’t achieve much, you’ll have to imagine a lot of them for yourself but for example the Money class could start life as pretty much a wrapper around a primitive:

public class Money {

    private double amount;

    public Money (double amount) {

        this.amount = amount;

    }

    // ...

}

Another argument against is that it increases memory footprint - and hey if that’s really really (come on is it really?) important to you then just use primitives.

Be Brave

I wish people would be a bit braver and use the code to express what they are trying to do and not worry about whether the way they are doing it is against Common Practice. Remember, the majority of software projects are still failures, so why follow Common Practice - it isn’t working!

eXtreme JavaScript

chris.probably — Sun, 05 Aug 2007 23:32:29 +0000

Over the past few months I’ve been working a lot with JavaScript. The language is very deceptive as it has C-style syntax, and is mostly written with little regard to good programming practice. However, it turns out to be quite a good object-oriented language which can lend itself to some very elegant code.

The language itself has a fair few problems for your average extreme programmer. For starters it’s a dynamic language so a lot of errors won’t turn up until you run it, and because of its tendency to not throw Exceptions (which do exist in JavaScript), things may just quietly go wrong. Code conventions don’t seem to have been established yet and there are an awful lot of different ways to do the same thing in JavaScript, for example declaring a class can be done like this:

function Monkey() {

    // constructor

    this.getBanana = function() {

        // ...

    };

    this.eatBanana = function() {

        // ...

    };

}

…or it can be done like this:

function Monkey () {

    // constructor

}

Monkey.prototype.getBanana = function() {

        // ...

};

Monkey.prototype.eatBanana = function() {

        // ...

};

or this…

Monkey = {};

Monkey.prototype = {

    getBanana : function() {

        // ...

    },

    eatBanana : function() {

        // ...

    }

};

… or you could even do it like this (although you’d have to be mad):

Monkey = function() {

    // constructor

};

Monkey['eatBanana'] = new Function("alert('eating banana')");

Monkey['getBanana'] = new Function("alert('getting banana')");

If you are doing extreme programming it can be much harder to come up with agreed standards just because there are so many different ways of doing things. This also makes refactoring a much more subjective affair and can lead to churn if developers enter the vicious circle of refactoring other peoples code to their preferred style. Also, its very easy to do (and it seems fun for some people) clever and complicated things in JavaScript which means simplicity of the codebase often suffers.

Shared Coding Standards

This makes me think when dealing with JavaScript it is very important to have shared coding standards agreed by the whole team. For the benefit of rooting some values of simplicity in the team its probably a good idea to agree a set of things that just shouldn’t be done (i’m thinking about the needlessly complicated things here). Similarly, when CSS and DOM manipulation are involved - the team should agree standard ways of doing things.

Feature Crawl

chris.probably — Sat, 12 May 2007 19:45:38 +0000

Have you ever experienced feature crawl? That time on a project when features seem to take longer and longer to develop and less seems to get done than it used to. There are several reasons why this can happen, but I want to talk about problems relating to the growth of the codebase over time.

As the codebase grows over time it seems to take longer to add a feature. Adding a new feature often involves working out what the existing code does, seeing what functionality already exists that you need to use and finding the places where this functionality is available. The bottom-line is, the more existing code you need to understand and navigate through - the more time it takes.

So what can you do to help? Write Screamingly Obvious Code - code that your grandma could understand, code that’s so easy to understand what and why it’s doing something that a monkey with learning difficulties could understand it.

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” — Martin Fowler

Pair Programming Patterns

chris.probably — Thu, 10 May 2007 22:47:27 +0000

I’m trying to introduce more Pair Programming at the moment - so I’ve been trying to make it a fun thing to do. One of the ways I’ve been doing this is making use of the Ping Pong Pattern which has been working quite well. However, there are situations when this pattern doesn’t fit such as when debugging, refactoring, looking for something in the code or when their are big tasks which are hard to divide up. When not using the Ping Pong Pattern, I find its easy for one pair to dominate, get bored, ~~silently think ‘OMG WTF is he doing?!!!’~~, or fall asleep.

So I’m going to just make some patterns up and list some ones I found which might be fun for those new to Pair Programming ~~and stop me falling asleep~~:

One Line Each - Each programmer takes it in turns to write one line of code. This can be done in silence as a kind of game, or normally to continuously discuss each programmers intentions.

Two Keyboards and Two Mice - Both programmers can interact at any time - the idea is to stop one programmer dominating / hogging (via Steve Freeman).

Chess Clocks - Sam Newman describes it much better than I could.

Pair Poker - Each programmer gets a limited number of cards at the start of the day, they can choose to play a card at anytime and gain immediate control of the keyboard.

Different Roles - Each programmer takes on a different role, possible combinations:

Refactorer / Programmer : One programmer cannot do anything but refactor, the other can do anything.
Tester / Implementer : One programmer cannot do anything but write tests, the other cannot do anything but make tests change from red to green.
Navigator / Programmer : One programmer can only move between classes, the other can do anything but move between classes.
Adder / Remover : One programmer can only add code, the other can only remove code.

Roles can be switched every hour or just when one get’s bored.

Thinking of a fun thing to do whilst debugging, looking through logs, or looking through code was a lot harder.

Backseat Driver - To keep both programmers attention, one drives and cannot do anything without being directed by the other.

Driver Buckaroo - The driving programmer has to give up the keyboard every time some event happens (e.g. build breaks, someone swears, you get an email, the project manager cracks the whip, someone checks in, someone stands up).

Promiscuous Pairing - Basically pairs rotate more often. (I’ve tried this with a rotation every 90 minutes — it was fun but tiring.)