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!

Getting your TODOs out of comments

chris.probably — Fri, 08 Jun 2007 22:12:26 +0000

Thoughtworker Carlos Villela talks about Getting your TODOs out of comments.

Genius.

Red, Green, Cup of Tea

chris.probably — Wed, 02 May 2007 20:55:23 +0000

I like the Red Green Refactor pattern - write a failing test, make the test go green and then refactor the code. However, I’ve found recently that refactor doesn’t necessarily mean make the code tidier or improve the design to some people. To some people it just means change some existing code.

So I invented (by accident) the Red Green Cup of Tea pattern - write a failing test, make the test go green, and go and make a cup of tea whilst the build runs. I’ve found that whilst making a cup of tea, my pair and I can reflect on what we’ve just done and often find we weren’t 100% happy with what we just did. We then set our cups of tea back down on the desk and Refactor the code.