A Month of Clean Code
What were my thoughts on cleaning and refactoring code before?
I never considered writing clean code an important part of software development. I considered designing the software as an essential part but didn’t want to touch the code that is written and doing its job. I never realized how much it matters.
However, once I was introduced to this concept in my training at Xebia, I realized that clean code and refactoring play an integral part in the software development life cycle.
Learning to write clean and refactored code is not a one day job. It’s a slow process that comes with experience. It starts with an understanding to identify that we are writing a bad code. And then we have to get our hands dirty, put in our sweat to make it better. Now, let us try to understand what is meant by clean code and refactoring. We will then cover how make our code better.
What is Clean code?
Easily accessible to others (straightforward, clear intent, good abstractions, no surprises, good names) — this is the most mentioned point.
- It is made for the real-world i.e. has a clear error-handling strategy.
- It is minimal (does one thing, has minimal dependencies).
- It is good at what it does.
Attributes of Clean Code
- No duplication
- Does one thing
- Meaningful names
- Tiny clean abstractions
- Expressive
- Unit tested
- Obvious — (The story of Obvious)
- Simple
Why refactoring and clean code matters?
- It makes developers productive.
- It makes it easy to add new developers.
- Easy to extend and maintain over a long time.
As a junior developer, it’s easy to argue that once code goes through the compiler, it’s all the same. Right?
The flaw in this argument is that it assumes that all software developers do is writing new code. The reality is that we spend much more time reading and modifying existing code than writing new code.
For this reason, code cleanliness and readability are paramount to project success. Writing clean and readable code is more important than your framework choice, test coverage percentage or project management solution.
Rules for writing Clean Code
Naming
- Use intention revealing names
- The name of the variable, function, or class, should answer three questions a) Why it exists? b) What does it do? c) How it is used?
- Method names should be meaningful. By naming methods poorly you can make your code difficult to understand.
- The method name should be precise.
For instance, a Table class containing a method that is used to create the table
Table table = new Table();
table.create() //appropriate
table.createTable() /*incorrect because table.create is sufficiently describing that it is being used to create the table.*/- Avoid disinformation in your names. We should avoid words whose meaning vary from our intending meaning
- Don’t call your interfaces something
- Don’t call your classes SomethingImpl
Functions
A reader can understand the control flow once they figure out which lines are unnecessary details and which lines are important, but that takes unnecessary effort, and someone who isn’t well versed with the code might get bogged down trying to understand what’s happening here.
A well written main method should read like a story. Just like each of the methods it executes, it should do one thing, do it well, and do it only: execute the right methods in the right order.
Comments
“When you find yourself in a position where you need to write a comment, think it through and see whether there isn’t some way to turn the tables and express yourself in code.”
Comments seem like a great way to make code more readable, but they can be dangerous as well. Why is this? Uncle Bob explains it best:
Because they lie. Not always, and not intentionally, but too often. The older a comment is, and the farther away it is from the code it describes, the more likely it is to be just plain wrong. The reason is simple. Programmers can’t realistically maintain them.”
The rule of thumb is as follows:
A comment is helpful if it describes what the code is used for. A comment is harmful if it describes how the code works.
Do write comments that describe what your class represents, what problems it solves, etc. Do not write comments explaining the control flow of your code. Comments that explain “how” your code works are an indication that your code isn’t clean.
If you need to explain why you’ve defined a variable or what a for loop is doing, write a named function instead. Document your code with your code.
Formatting
“Code formatting is important. It is too important to ignore and it is too important to treat religiously. Code formatting is about communication, and communication is the professional developer’s first order of business.”
When different blocks of code in the same project look different, it causes the reader to wonder whether the differences are functional or stylistic. This is bad because it increases cognitive overhead.
Your reader should never have to ask this question because it unnecessarily increases the overhead required to understand the project. If you’re constantly forced to manually separate style differences from functionality in your brain, you’re wasting energy on making a distinction that should have been made by the author.
As an author, don’t make your reader work any harder than they already have to. It doesn’t matter what your style rules are — just pick some and be consistent. The best way to do so is by codifying them into linter rules and enforcing them at build time.
Conclusion
I hope these tips have inspired you to push yourself and your team towards better and more maintainable code. If you haven’t yet read Clean Code by Robert C. Martin, you should pick up the book as soon as possible. It made me a better programmer, and it can make you a better programmer too.
