A guide to clean code for new developers

Why should anyone even care whether their code is 'clean' or not?

Indeed, the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code. ...[Therefore,] making it easy to read makes it easier to write.

Robert C. Martin, Clean Code: A Handbook of Agile Software Craftsmanship

I think he put it rather nicely.

So we know why we should care... but what is clean code, exactly? What separates clean code from messy code?

This is the answer I prefer: code is clean when it's easy to read, easy to understand, and it's organized in a way that makes sense to other people.

Now that we have a definition, what exactly can you do to clean up your code? I've outlined my best advice below.

Making your code easy to read.

• Shorter code is usually better.
  If the function can be written in one line, there's no need to write it in two, and anyone reading will be very grateful you didn't.

• Whitespace is your friend, and too much whitespace is far better than too little.
  Text, in general, is much easier to read when it's generously spaced, but it tends to feel overwhelming when it's too dense and it becomes harder to keep track of your position in the document.

To illustrate:

Here's some dense code,

import function from modulevariable = function(argument)variable = function(variable)def my-function(argument):   do xyzvariable = my-function(variable)

And here's some well-spaced code.

import function from modulevariable = function(argument)variable = function(variable)def my-function(argument):   do xyzvariable = my-function(variable)

See the difference?

• The length of any line in your code shouldn't exceed 80 characters.Your code will be easier to read in many short lines, instead of a few very long ones. There's nothing magical about the 80 character limit, but I find it a convenient rule of thumb, and anything much longer quickly becomes a pain to read.

Making your code easy to understand.

• Writing too many comments is much better than writing too few.
  Comments can sometimes feel bothersome to write, but whenever you write any code that is even slightly complicated, you should have a short comment before it.
  The comment should explain what you were trying to achieve and if it's a very complex piece of code, briefly documenting why you chose that approach might be a good idea.

• Long identifiers are better than cryptic ones.
  Sometimes, it feels hard to express the purpose of a variable or a function in one word, and writing a multi-word variable name can feel awkward.
  But it's still better to use a long name that clearly explains the purpose of a variable than one that is short but cryptic.

• Avoid nesting where you can(but keep line length in mind).
  

  if x and y and z:    pass

is easier to understand than

  if x:    if y:      if z:        pass

but

if black and white and blue and red and green:      pass

is harder to understand than

    if black and white and blue:      if red and green:        pass

Organising your code.

• As much as is reasonable, DRY(Don't Repeat Yourself).
  When you find yourself repeating the same(or very similar) code in more than two different places, you would usually be better served turning it into a function and calling it twice instead. Your code ends up being shorter, and making future changes becomes much less of a hassle.

• Side effects are evil, so use with (extreme) caution.
  Some functions accept parameters and return a value, and do nothing else. That's what an ideal function looks like. Impure functions cause side-effects: changing a global variable or class attribute within the body of the function, for example. Side effects are evil because they generally make debugging a pain in the behind: You end up having to scrutinize each line of code to understand where the heck the value of your variable is coming from.

• Your functions should ideally do only one thing.
  Functions that have more than one job are usually much longer than they should be and tend to cause much confusion in the code you're calling them. To use an analogy, if you asked a friend to grab you a book and he returned with a shoe in his other hand, wouldn't you be really confused? It's the same idea with your functions, so please don't confuse the poor folks who end up using or changing them. Your function should do what its name says, and nothing more.

Summary

• Keep it short
• Space it out
• 80-character lines
• Write lots of comments
• Use good names
• D.R.Y
• Pure functions
• Simple functions

Conclusion (Putting it into practice).

No one keeps an eight-step checklist in their head as you're trying to solve a problem or fix a bug, so how does anyone manage to write clean code? Simple. We don't, at least not at first. The answer is called refactoring, and it means changing code without affecting the output.

After you're done with one piece of code, stop. Take ten minutes to breathe. Look away for a little while. Then go over the code you just wrote, and fix any messy bits you find.

Over time, writing clean(er) code will become more and more of a habit, and you'll find progressively fewer mistakes when you refactor.

Further Reading

I tried to make this post as useful as I could, but a full, in-depth treatment would probably require writing a short book. Here's some extra content you'll find useful if you want to learn more about writing clean code.

• The Zen of Python
• Clean Code Explained
• Clean Code: A Handbook of Agile Software Craftsmanship