Identifiers CAN Say Why

A while ago I wrote about the rule of thumb I use to decide when to write a comment: "Identifiers say what. Comments say why." Since then I've had the pleasure to work on a couple of projects with Ivan Moore and he's shown me that it is possible for identifiers to say "why" as well. His style is to use a few long and descriptive identifiers to explain why particularly odd or complex pieces of code exist in the system. I've started using the style as well and found it to be very useful. For example, here's some code from an imposteriser in jMock 2:

    private <T> Class<?> createProxyClass(Class<T> mockedType, Class<?>... ancilliaryTypes) {
        Enhancer enhancer = new Enhancer();
        enhancer.setClassLoader(mockedType.getClassLoader());
        if (mockedType.isInterface()) {
            enhancer.setSuperclass(Object.class);
            enhancer.setInterfaces(prepend(mockedType, ancilliaryTypes));
        }
        else {
            enhancer.setSuperclass(mockedType);
            enhancer.setInterfaces(ancilliaryTypes);
        }
        enhancer.setCallbackType(InvocationHandler.class);
        enhancer.setNamingPolicy(
            NAMING_POLICY_THAT_ALLOWS_IMPOSTERISATION_OF_CLASSES_IN_SIGNED_JARS);
        enhancer.setUseFactory(true);
        
        Class<?> proxyClass = enhancer.createClass();
        return proxyClass;
    }

It's pretty clear, I think, why that naming policy is being used.

This style works well for enterprise software. Computer software, being precise and logical, is never a good fit for the messy, illogical ways that groups of people work together¹. Elegant code will need some clunky workaround for strange organisational decisions, and it's important to clearly explain in the code why those workarounds exist. Hopefully it will allow programmers to remove the kludge after the next round of reorgs reshuffles the management again.

Copyright © 2007 Nat Pryce. Posted 2007-04-24. Share it.