Code is for HUMANS

The other day I was having a discussion with some coworkers about code style. I wanted us to implement style checking for all of our Java code. Not everyone agreed that code style was important, and the point was made that differences in code style were like a fingerprint for the programmer who wrote the code. At the time I didn’t have a good response. Yet I felt that this kind of uniqueness was a bad thing.

I’ve thought about it some more and I have come to a conclusion. The reason variance in code style is bad within an organization is that the code we write is for other people.

This is an important point, so I am going to repeat it:

Code is for humans. Programming languages are for the convenience of people, not for computers.

If all of our code was written in the most optimized possible form for a computer we would write all of our software in binary. Maybe there’s someone out there who still does this, but most programmers use high level programming languages like C/C++, Java, Python, JavaScript, etc.

There are myriad articles about how code is read more often than it is written and that most programming jobs are more about maintaining existing software rather than writing completely new code. I don’t want to try and reproduce those articles. Instead I want to talk about what makes code readable.

If you agree that code is written for other people to read, then it follows that we should be optimizing our code for readability. This is where my argument in favor of style checking comes in to play. Having a common style for code allows you to ignore boilerplate and focus on logic.

Consider this terrible Java code:

for ( int idx=0; idx<limit; limit++ ) 
{
  if (thing == null) 
    throw ThingIsNullException;
  else {
    doThing();
  }
}

Aside from the fact that this code doesn’t do anything, what makes this code so bad? It would compile. It’s syntactically correct. But it takes more time to read than it should because your brain is being forced to remember all the valid possible syntax for Java. If this code had a single style throughout you would be able to largely ignore the control structures and just think about what logical operations are being performed. This may not seem like much of a problem to you from that tiny snippet, but try to imagine a variety of styles across a million lines of Java. Think about how much extra cognitive load is being put on you when you have to read and comprehend all of the boiler plate. Imagine reading a novel written by multiple authors where each author wrote a paragraph or two, then handed the next section to another author who completely changed the style. This would make for a novel that was very hard to read because you’d be constantly adjusting to different writing styles instead of enjoying the story. Confusing your readers is not a nice thing to do in any medium.

This is why code style matters.

If everyone uses their own preferred style then eventually the code will look like a mess and any future programmer will have to take on the added cognitive load that comes with trying to read messy code.

Great. We’ve established that a problem exists. What’s the solution?

This is where things get a bit fuzzy. There are lots of opinions about what makes for “clean code”. Here’s my definition of clean code:

Uniform style, proper use of language idioms, and clear separation of concerns.

Having a uniform code style that is enforced by a style checker is the easiest of part of my definition to implement. Most programming languages have a mechanism for checking code style. Java has checkstyle, Python has pylint, etc. Go went so far as to build style checking into the language for many of the reasons I’ve discussed. So there is really no excuse for not having a uniform code style in an organization. Personally I think adopting the most commonly used code style of any language I use is the right approach, however having a uniform code style is far more important than the style itself.

The rest of my definition is a bit more difficult to enforce since it requires experienced programmers rather than good tools. As anyone who has ever tried to learn a foreign language knows it’s hard work to learn the idioms of a language. However, once you learn the idioms of a language you are truly fluent and better able to communicate with native speakers of the language. The same is true in programming. Using idioms you learned in Lisp won’t necessarily translate to Java or Ruby. So it takes time and experience to learn to program idiomatically in any language. The is also true for learning how to use the abstractions of a language to properly separate concerns.

There are a couple of things you can do to improve the overall use, and quality, of idioms and abstractions. The first is code review. In a good code review process programmers can help each other make their code more idiomatic while making use of the right levels of abstraction. Pair programming is another tool that can be useful for creating clean code. I also find that writing unit tests can be very valuable. When I write tests I often find ways to improve the code I am testing. This isn’t quite as good as having another programmer look at my work, but it’s better than nothing. As an added bonus unit tests provide proof that my code works, and they can serve as examples of how the code should be used when the next programmer reads it.

Writing code that works is nice, but it’s not enough. Really great programmers write code that is simple for the next programmer who needs to use, modify, or maintain it.