The Importance of Clean Code

The Importance of Clean Code

I’m a contractor, so I see lots of different coding styles and messy code is the bane of my life. This isn’t bad code as such, or even spaghetti code, just messy.

Messy code is bad for a couple of reasons. It makes long-term maintainability harder, especially when you’ve got a team of developers. It makes it harder for new developers to join the team. It’s a compound problem too: the longer you accept messy code as ok, the messier the code gets. And it’s just not enjoyable development.

Now think about messy enterprise software. These are applications where the lifetime is measured in decades, not merely years. Look at COBOL if you don’t believe me on how long software can last in enterprises…

What Makes Code Messy?

Other things being equal, simpler explanations are generally better than more complex ones

Occam’s Razor

Lot’s of things make code messy, but lots can be boiled-down to needless complexity. Let’s consider some examples of mess that I’ve seen recently.

Inconsistency

I find it easier to read consistent code, especially in terms of indentations. If a line of code is indented once more than the one above it, I know it’s a subroutine of that line. If the indentations are incorrect then it takes longer to understand (and more brain-power too).

Consider the following:

if (someVar) {
doThis();
if (someOtherVar === false) {
nowDoThis();
    nowDoThisAgain();
}
}

Vs:

if (someVar) {
    doThis();
    if (someOtherVar === false) {
        nowDoThis();
        nowDoThisAgain();
    }
}

Exactly the same code, just the bottom one is easier to read. If I asked you to add an else statement to if (someVar), which one is easier to know exactly where to go?

Forced indentation is one of the reasons I like Python.

Short Lines

Keep lines of code short and to the point. I’m not saying that every if statement should be on a new line (I’m ok with if (invalid) { throw new Error("uh-oh"); } on one line), but it should be readable.

I recently saw a line of code similar to this (variables changed to protect the author, but it was this long):

ioc.singleton('moduleName', function(container) { return new MyModuleProvider(container.get('someDep'), container.get('someOtherDep'), container.get('yetAnotherDep'), container.get("yetAnotherotherDep"), container.get('yetAnotherDep')) });

The original line was THREE HUNDRED AND SEVENTEEN characters long. I’ve shortened it to make it readable for this article (this is a mere 240).

Answer me this, just looking at the code (ie, not editing it in any way):

  1. can you tell me how many arguments go into the constructor?
  2. what are the dependencies?
  3. what linting errors are in there?
  4. will the code work?

Because I can’t. I also duplicated one dependency which I bet you never noticed.

Most IDEs have a line which shows where they recommend you should end (WebStorm’s is at 121 for example). I usually set my linting to 80 characters, but it should always be displayed in the developer’s IDE without having to scroll right.

As a related point to this, I like to keep all my files to 500 lines or fewer. Long files are almost as difficult to read as long lines.

Avoiding Messy Code

This can be an awkward, because all developers write code that (they claim) they can read. Certainly all the developers who wrote the examples I’ve picked claim they can read it and that I’m at fault for finding it hard.

If you’re writing in a language with good linting tools then implementing those will help. Ensure that you enforce a maximum line length and indentation length and styles. This will help. There are also external tools, such as bitHound or CodeClimate if you can’t run them on your build.

Largely, however, this is a cultural change. As a developer, it’s your responsibility to educate your teammates as to the benefits of cleaner code. Pair programming and writing clean code yourself will help.

And ultimately, reject any code that you feel is not up to standard. I know this might be hard if you’re up against a deadline, or you’re a junior developer. However, once that software gets merged into the main development branch, you are responsible for maintaining it.

Things to Remember

  1. Each file should only contain one class*.
  2. Each class* should only do one thing (single responsibility).
  3. Document your code. Each file should have a note explaining it’s purpose and each method* should have more detailed notes. THERE IS NO SUCH THING AS SELF-DOCUMENTED CODE!
  4. Keep your files short - ideally under 500 lines, definitely under 1,000.
  5. Indent properly.
  6. Get other developers to review your code. If they can’t understand it, refactor it while you remember it.
  7. Logically group your unit tests so they become practical examples of how your code works.

* I know not all languages are object-oriented, so a class might be replaced with a routine or function. Use your best judgement.


If you don’t believe me how long you could be lumbered with someone else’s shitty code, may I remind you of COBOL?