As beginners, we probably start hearing about clean code when we're trying to level up our coding skills. Prior to this, almost all that mattered was writing code that works. This isn't bad, even experienced people do the same. The difference between us and experienced software engineers is, they usually refactor their code; They clean up previously written code to make it more readable.
Testing waters
Our next thought must be, how do we write clean code, what does it look like? Before we start thinking of principles or steps, we need to take our minds back to the code we've previously written. Whether you are learning to code in java, python, javascript, or some other programming language with hopes of building the next awesome thing. We have all used built-in functions in these languages. Think about all the times we made use of a built-in function, and the function names almost spelled out what those functions did. We may have also started using stackoverflow and the likes to find coding solutions. Think about solutions that were so easy to read and understand, we most likely copied the most readable. The most readable is usually the most understandable.
Defining clean code
This brings us to definitions of clean code. Readable code; Code has to be machine-readable, but more importantly human-readable. We will be looking at the definitions of clean code from the perspective of a few software engineers. This will be an attempt to helps us begin to see clearly what clean code is all about:
Bjarne Stroustrup said,
I like my code to be elegant and efficient, clean code does one thing well.
A good example will be to think of all the math functions we could perform. We could calculate the factorial of a number, find the square root of numbers, and so on. The best-case scenario would be to have a math class or object, with all these methods we could call individually. This would ensure minimality, we would almost certainly know what we are getting with each function call. Each function call would be handling one mathematical operation.
Grady Booch said,
Clean code is simple and direct. Clean code reads like well-written prose.
This definition also takes into account minimality and simplicity. It also stresses one thing, "..well-written prose". This aspect has to do with the naming of functions and variables. It is not enough for our code to be simple, with functions that execute one task. Our code also has to be human-readable. Going back to our math object with functions analogy, the function name add cannot be used for an algorithm that subtracts. The name given to a function or variable helps the reader take the first step in demystifying what that piece of code does. We have to be intentional when naming our functions and variables.
Practical Steps
Going forward, we want to highlight basic things we should be doing to ensure we write cleaner code:
Commenting
Our first thought must be, "Yes! Lots of comments". On the contrary, you should avoid lots of comments. Robert Martin said,
The proper use of comments is to compensate for our failure to express ourselves in code.
Although there are use cases for comments, a good example is a legal comment, we should use comments sparingly and as a last resort to explain code that might be difficult to read.
Naming
There is a popular convention for the naming of variables and functions. Variable names should be proportional to the scope that contains them. This implies that the bigger the scope, the longer the variable name. For functions, it is the total opposite. As the scope of a function gets bigger, the function name should be smaller.
DRY - Do not repeat yourself
Oftentimes, when we are building a project, there are functions or pieces of logic that we have to use in multiple parts of the project. Extracting reusable logic would make our code more readable.
Functions
When writing functions, there are a few things we should keep in mind:
- Smaller code is better, usually more readable. This means we should refactor as much as possible.
- Functions should not have multiple nested structures to ensure their simplicity and readability.
- Function arguments should be few. We can pass objects where possible.
- Our functions, ideally, should be pure functions. If our function is returning a value, then it should have no side effects.
What Next?
Looking to dive into writing cleaner and readable code? Amongst the numerous contents you can find on the web, I would recommend reading this article and getting this book. Cheers!
Cover photo by Goran Ivos