Clean Code is not just a nice thing to have, but it’s a necessity. Without quality code, the project will face could fail due to an accumulation of technical debt.
Introduction
Purposes of this chapter:
what clean code is;
why clean code is important;
look at some exceptions to rules we’re going to explore.
The meaning of Clean Code
There is no strict definition of Clean Code and so there’s no way of formally measuring clean code, so there is no tool capable of saying if our code is “clean” or not. Some tools (like static type checker) can be useful, but not sufficient. In general Clean Code is something that professionals can decide.
Programming Languages are not just a tool that allows us to communicate with machines, but it’s also a way to communicate our ideas to other developers. Here is where the true nature of Clean Code lies. So Clean Code is something that comes from ourselves after having understood the difference between good and bad code, having identified the traits of good code and good architecture.
The importance of having Clean Code
Some reasons why Clean Code is important:
code maintainability
reducing technical debt
working effectively with agile development
The code needs to be maintainable and readable. Otherwise, every time product management asks for a new feature, you have to stop to refactor and fix technical debt. Technical debt refers to the concept of problems in the software as a result of compromise or bad decisions being made. This concepts resolves around these two questions:
What if the problems we are currently facing are the result of previously written bad code?
If we decide to take a shortcut now, instead of investing time in a proper solution, what problems are we creating for ourselves further down the line?
The word “debt” indicates that the code will be harder and/or expensive to change in the future than it would be to change it now.
Some exceptions
There are such cases where it’s possible to relax some of the constraints given by clean code rules. In these cases common sense applies. A few examples:
hackatons
simple script for one-off task
code competitions
when developing a proof of concept
when developing a prototype
when you’re working with a legacy project that will be deprecated, and it’s only in maintenance mode for a fixed, short-lived period of time.
Code formatting
There are some Coding Standards that state how the code should be written and formatted. The most well-known one is PEP-8 and it provides guidelines on how we should write programs in terms of spacing, naming convention, line length, and more. However, Clean Code goes beyond that: it’s about achieving quality software and building system that is robust and maintainable. On the other hand, formatting code correctly is important to work efficiently.
Adhering to a coding style guide on your project
A coding guideline is the indispensable minimum a project should have in order to be considered developed according to quality standards. Ideally, there should be a written document for the company or team you’re working in that explains the coding standard that’s expected to be followed. In particular, in Python, the reference for coding style is PEP-8. Here’s the main principles of PEP-8 considered as quality traits:
Searchability: this refers to the ability to identify tokens in the code at a glance. For example, one of the key point of PEP-8 is that it differentiates the way of writing the assignment of values to variables, from the keyword arguments being passed to functions:
location = 'Tokyo' # assignment of values to variablesfind_location(location='Tokyo') # keyword arguments being passed to functions
PEP-8 establishes this convention:
use spaces when setting values to variables;
don’t use spaces when passing arguments by keyword to a function.
Consistency: code should be consistently structured to that it is much easier to read and follow. If everyone on the team is doing things in their own way, then the code will be error-prone, misleading, and full of bugs.
Better error handling: limit the amount of code inside a try/except block to the minimum possible. This reduces the likelihood of accidentally swallowing an exception and masking a bug.
Code quality: with good quality code it is easier to understand the code at a glance and find bugs and mistakes.
Besides formatting, there are more considerations to take into account, which will be the next two topics:
Documentation (documenting design decisions in the code)
Tooling (using tools to leverage automatic quality checks)
Documentation
Good code is self-explanatory but is also well-documented. Note that documenting code is not the same as adding comments to it: indeed we’ll talk about docstrings and annotations besides code comments.
Code Documentation is important in Python for two main reasons:
being a dynamic typed language, it might be easy to get lost in the values of variables or objects across functions;
we can run some automatic checks, such as type hinting, through tools like mypy or pytype.
Code comments
General Rule
As a general rule, we should aim to have as few code comments as possible because our code should be self-documenting.
As a consequence of this general rule, this means that if we use the right abstractions and name things clearly, then comments shouldn’t be needed. The literature on software engineering states that comments in code are a symptom of our inability to express our code correctly.
However, in some cases comments could be necessary and this is typically the case when something in the code is done for a particular technical nuance that’s not easy to understand at first glance (for example, if there’s a bug in an external function and we need to pass a special parameter to circumvent the issue).
Another kind of comment in the code that is definitely bad: commented out code. There’s not good reason, especially now with modern version control systems, to leave commented out, which brings chaos and contradictions.