Keeping those codebases gleaming, one duster at a time, and helping understand one of the hardest problems in computer science.

I was honoured to be able to speak to Built In Boston about how we do clean code at Mimecast! You may or may not know but Mimecast has a major office in Boston, it’s where around half my current team are located. You can find the full article here.

What Is Clean Code?

For those that don’t know, Clean Code is a paradigm that favours readability. It works on the premise that everyone in the team should be able to understand the code by looking at it first time. The idea is that by making it readable, you make it easier to maintain and easier to debug for others when you inevitably leave.

Well OK, what does that look like?

So let’s think about a bit of Java code that will be used for adding sheep to a herd. This is intentionally unreadable…

Group h = new Group(20);
for (int i=0; i<=20; i++) {h.add(new Animal())}

OK so reading through this we know a herd is a group so lets use a Group object, and we need 20, that sounds about right for a herd capacity. I don’t like typing so let’s call the herd h and then we will loop though adding a type of Animal to the herd h.

Let’s be honest, the only reason you know that’s adding sheep to a herd is because I told you at the beginning right? Also hardly any spacing, terrible. It’s very difficult to read.

Let’s change that to something slightly better, which is probably what most software professionals type to without thinking about Clean Code:

Herd h = new Herd(20);
for (int i = 0; i <= 20; i++) {
    h.add(new Sheep())
}

OK so this is better. We know we’re adding Sheep to a Herd, great. But what if later down the line we use h again. What if we have a herd of goats in a wider farm? h will get confusing no? What’s our fixation on 20? What does it mean? We are wasting time trying to figure out these things even in this simple scenario! So let’s think of some better names and think if we can make this small snippet even cleaner.

int SHEEP_HERD_CAPACITY = 20;
Herd herdOfSheep = new SheepHerd(SHEEP_HERD_CAPACITY);

for (int count = 0; count <= SHEEP_HERD_CAPACITY; count++) {
    herdOfSheep.addToHerd(new Sheep())
}

So I think this is the best for our example. We know our herd is a herd of sheep. We know that the herd capacity is 20. We can make this cleaner by injecting in the capacity from a properties.file perhaps so that we don’t have to keep changing the code if we want to change the herd capacity.

One Of The Hardest Problems In Computer Science

Did you know that Clean Code involves one of the hardest problems in computer science? Let’s inspect the loop counter above……

Although using i as a loop counter is a known convention, what if you’re new to coding? Why not call it count so everyone knows it’s a count? Finally give menthods meaningful names. Now, it could be argued that add() may suffice. You could think that herd.add(new HerdAnimal()) would mean adding a type of HerdAnimal to a Herd. But what if this Herd is not simulating a serene farmland, but instead is a video game where various herds of animals attack each other? Adding aggro is a gaming term in these kind of kind of games so now does the add() function add to the herd of add aggro to a sheep in the herd ready for combat?

OK, convoluted. But….. this is a really simple few lines and we have already highlighted some issues with not having clean code. One of our jobs as developers, engineers and other software professionals is to crush ambiguity and make things clear. If we can’t even do that in our code how can we expect to do that when refining ideas? So saying the method is addToHerd() makes the intention clear from the get go, avoiding changes later down the line, and most importantly avoids confusion!

So as the Phil Karlton quote states, we’ve covered one of the hardest problems of Computer Science and Clean Code…. naming things! But also Clean Code is much more than that…..

Magic Numbers

No, not the band The Magic Numbers. No, not the number of protons neutrons in a fell shell referred to as magic numbers in physics either…. magic numbers in code, of course!

We actually came across one in our example above: 20!

Magic numbers are random numbers in code that clearly mean something but exactly what?! Who knows! Unless you wrote it, and even then, based on experience, they can be difficult to understand!
By assigning the variable SHEEP_HERD_CAPACITY to 20, we make clear what 20 actually represents rather than just the value. Magic numbers are not clean code and can get incredibly confusing. Let’s get rid of them!

So anything else?

LOADS MORE! Much more than we can say in this brief post – Dependency Injection, Pair Programming, Behavioural Unit Tests, much more! Please do ready the Built In Boston article and take a deeper look into the Clean Code paradigm to find out more!