Thursday, 14 June 2012

Can you read your own code?

I have been reading a lot lately into how to produce better quality and code of a more professional standard.

A lot of focus is put on the readability of the code especially to future developers who may be performing maintainence.

I was recently working on a project written in grails and specifically on a service called TranslationService. This is a fairly simple service which wraps a call to the internal grails messageSource object. Within this service we resolve a locale from a locale resolver that we have written and pass this through to the messageSource object.

We wanted to change this to allow us to pass through a context and from this context retrieve a locale resolver from a map while defaulting to the original locale resolver we had defined as a property of the service. So while pair programming with a grails and groovy newbie we began.

The original line of code before it was changed is shown below.

"def locale = localeResolver.resolveLocale(request)"

The following line of code is the result of our efforts.

"def locale = ((localeResolverMap ?: [:])[context] ?: localeResolver).resolveLocale(request)"

We primarily develop using a TDD method and our initial effort had most of the logic being performed in another private method on the service. With tests written and the functionality correct we began to re-factor and the line of code above is the result.

At first the final result was very pleasing to the eye. From a method which initially was about 5 - 10 lines in length we had re-factored to one line. Knowing it worked it has been deployed. Since then I have been thinking about the readability of this line.

We called over an experienced grails/groovy colleague and asked him to try and explain without any context what the line of code did. While he did work it out it was not immediately obvious.

Effectively we have a line of code that while pleasing to the original author and ultimately readable by experienced developers it would be slightly more difficult to a novice developer or someone trying to make a quick fix a year from now.

So what are the options?
  • We could leave it as it is and to hell with the future developers. If they are not skilled enough to work out what the code is doing then they should not work on the project itself.
  • We could comment the line of code to explain what we are trying to achieve.
  • We could factor the line of code out into a method and give it a clear descriptive name.
  • Where a clear and descriptive name is not available or feasible we could factor out into a method and comment the method itself.

Each of these options can be performed without too much work but which do we go with?

The first option of leaving it as is is not the best approach. While the possibility of making another developers job harder it has the possibility of myself returning to this code in a year or two and having to work it out myself. I for one am all in favour of making my life easier. In this instance the code is not too complex and people who can program in groovy should be able to work it out, but I am using this example to make a wider point. So for arguments sake lets say this option is out.

Commenting single lines of code is out too. I don't like this approach. While I agree comments should be used, I think they should explain a class or method and not individual lines of code.

Factoring code out to a single method with a clear and descriptive name. Sounds perfect. But what is that line of code doing? In essence it resolves the locale. But it does more than that. It gets the locale resolver based on a context and from a map if that context is a key in the map or the default locale resolver. Not as easy to get that in a method name that is clear and concise.

So we are left with a method with a clear and concise name and a comment on that method. This ties in nicely. We still get to keep out nice, complex and tested one line of code while still allowing all future developers an easy job of working out what it does.

At the end of the day the code we write is an evolving entity, and making the job of developers extending, modifying or improving this code easier is something we need to be thinking about very seriously. All too often do we hear everyone in the office complaining about the code they are having to read through. So from now on I am going to make a real conscious effort to improve the readability of mine.

Domain Name Optimisation - the New SEO

When the Internet Corporation for Assigned Names and Numbers (ICANN) was formed in 1998, it was given responsibility for overseeing the workings of generic domain names such as .com and .net, as well as country-specific domains such as .uk, and ensuring that control was delegated to the appropriate organisations. As a simple example, the .uk domain is actually managed by Nominet in Oxford.

In 2011, ICANN's directors voted to allow any organisation willing to pay $185,000 up front (and a further $25,000 per year) the ability to register their own generic and regional top level domains. The list of all applicants was released on June 13th 2012, and contains a number of applications that were to be expected:

MICROSOFT Microsoft Corporation
APPLEApple Inc.
IBMInternational Business Machines Corporation

and a lot more that weren't:

PIZZAFoggy Moon, LLC
Asiamix Digital Limited
Uniregistry, Corp.
Top Level Domain Holdings Limited
MUSICDotMusic Inc.
DotMusic / CGR E-Commerce Ltd
CY/AP Community
dot Music Limited
Amazon EU S.à r.l.
Victor Cross
Charleston Road Registry Inc.
.music LLC
Entertainment Names Inc.
SEARCH Charleston Road Registry Inc. 
dot Now Limited
Amazon EU S.à r.l.
Bitter McCook, LLC 

These are all very generic terms, ones that you could imagine yourself searching for rather than visiting a known site. Check on your browser: that searching can just be performed by typing the word or words into the URL bar, which sends the user to a search engine showing those terms. Try it now - just type "pizza" and see what happens. Me? I get Dominos as my top hit.

But there is no technical reason why one of these companies, once they've gained control of this top level domain, cannot run a website on just that name:


This is exactly the way thousands of companies' internal websites work. When a single word is entered into a URL bar the browser will first check to see if that is a valid website; only if it isn't will it pass control over to the search engine.

These new domains will allow registrars to take users - their potential customers - directly to their own websites when they put "pizza" into their web browsers, cutting out the search engine entirely. This isn't Search Engine Optimisation, this is Domain Name Optimisation, and for $185,000 it is almost certainly worth every last cent.