Travel, tech and food

Trying to be a half-decent programmer: what is readable code?

When you are coding you will often have a choice between doing it fast and doing it well. The correct choice obviously depends on the context of the product – projects vary. For example, the way a startup codes vs a large company will naturally be different. The way an airplane is programmed will be different to a dating app. In all situations though, it’s likely other people will be looking at your wonderful code in the future!

So it’s important to consider how to write – even if it’s quick and dirty – in a way that is easy for others to understand. Many know the sinking feeling of having to delve into an old codebase to fix a bug and thinking there must be a special place in hell for certain programmers.

Making code readable is about minimising the time it takes for a fresh pair of eyes to understand what your code is doing – making it easier to maintain and extend. To do this, we need pay attention at every level, from the variable naming to the way the classes in your project interact.

Coding style is a lot about our personal preferences, but there are techniques which can clearly make code simpler to comprehend quickly. Summarising some of my favourite tips to keep in mind that I found in ‘The Art of Readable Code’ by Dustin Boswell and Trevor Foucher:

Code that does multiple things = harder to understand

  1. Naming variables and functions better:
    • Give variables a clear, unambiguous name that explain what they should store (and if appropriate, the unit e.g. cm)
    • Following conventions like uppercase CONSTANTS
    • Don’t use negative boolean names
    • Function names that say what they do to input, not the output they produce
  2. Make the inherent logic easy to infer quickly
    • Group bits of code based on what they do inside a function and leave gaps – in the way you leave lines between paragraphs
    • ‘Defragment your code’: extract subproblems into separate functions, or even better into utility classes that can be easily reused
  3. Think about how much mental ‘memory’ you need to think about the potential ways a given piece of code can run
    • Restrict the scope of variables – the more places they get used the harder they are to keep track of
    • Avoid many levels of nesting – try and simplify large if statements, don’t loop within loops
  4. Make the code easy to understand for someone reading it the first time
    • Use comments ‘wisely’ to record your thoughts, important high level interactions, and any potential pitfalls
    • Think about how you would explain the code in front of you in plain english
    • Write compact code, but not excessively – it may be appropriate to use an extra variable to make it clear what is going on, rather than squish everything inside a function
  5. Write less code altogether
    • Don’t bother implementing features you don’t need yet, and remove any unused ones
    • Use libraries
  6. Write focussed, easy to understand tests – scary looking tests will put people off modifying your code!
    • Hide unimportant details from your main test functions using helper functions
    • Try and boil the tests down to a point where you can clearly see a ‘ with this input you should expect this output ‘
    • Choose good inputs, that thoroughly test the code
    • Give tests a name which explain the situation / bug they are testing

See also:

Photo by David Dennis on Flickr (cc)