Published: Nov 06, 2022

Clean Code

Introduction

Every day more and more parts of our lives are controlled or influenced by software. So far this field has been quite unregulated and software engineers mostly enjoy a high degree of freedom in choosing their tools, libraries, languages and ways to solve problems. Compared to other professions there are not many laws dictating what can and can’t be done or how it has to be done. In my opinion this allows software engineering to rapidly innovate and shift as quickly as it currently does. It also means that software engieers have to create their own rules and standards. Should they fail to do so lawmakers will eventually be given enough reasons to start regulating.

When software development started in the 1950s there were many attempts to mathematically proof that a piece of software behaves as expected. Due to the ever growing complexity of software this practice was abandoned for most projects. Instead engineers focused on writing tests and keeping their code clean to catch most bugs.

This post is heavily influenced by lessons about “Clean Code” from Robert C. Martin (aka. “Uncle Bob”). I highly recommend watching all his lessons which are available for free on youtube. This post is not a replacement for those lessons but a very brief reminder/summary.

At this point I’d also like to insert a quote from Edsger W. Dijkstra that I always try to keep in mind while writing or refactoring code.

Simplicity is prerequisite for reliability.

Clean code is profitable

Some might think clean code hurts profits because it requires more time to write. What’s the point if you already have full coverage using tests?

Clean code allows for much faster development and response to customer feedback in later stages because it’s modular and easy to modify. This also makes it easier to apply the DRY principle (Dont Repeat Yourself) since parts of the code can easily be extracted, packaged in a library and shared between projects.

Only with clean code is it possible to add more developers to a project and expect faster progress. Having bad code means that existing developers have to spend a lot of time explaining the bad code to the new developers, delaying the project even further. The new developers will then learn from the bad code and produce even more bad code.

What makes code “clean” ?

  • One function does one thing
    • A function does one thing if it is no longer possible to extract a meaningful function out of it
  • A functions only uses functions that are one abstraction level below the function itself
    • Don’t start manipulating bytes in a high level function, create a new function instead
  • Clean code is polite to the reader
    • Think about a news article. It has a headline, titles and paragraphs which easily allow the reader to get a high level overview, dive into details when interested and exit at anytime.

How to write clean code

The rules here are not set in stone, treat this more as a rough guide to help you look for parts of code that can be cleaned up further.

  1. Write code that works
    • Premature optimization is the root of all evil!
  2. Extract, extract, extract
    • You might find functions that operate on a common set of variables. That’s what we call a class in OOP.
  3. Use meaningful names
    • Names of variables should be proportional to their scope
      • If the scope is just one line, a single letter is fine
      • Class members have longer names ~2 words is usually fine
    • Names of functions should be inversly proportional to their scope
      • Public functions should have short and simple names
      • Private functions usually have longer names. The further it’s nested the more specific is the thing it does and the more description it usually needs.
  4. Functions should not use more than 3 parameters
    • Boolean parameters can often be moved to an if statement in a new function instead
  5. Use comments as a last resort
    • A comment is a failure to express something clearly with code
    • Make them stand out in your IDE (try bright red)
    • If you use TODO: comments, never check them in. Either finish the task before checking in or use issue tracking software.