How to improve your code readability? Useful clean code ideas to know

In many ways, working in software industry is like working in industries such as construction or interior design. It requires knowledge and precision. When you work on a giant project with many features, sometimes it feels like analyzing DNA strings on inventing a vaccine for the worst threats to human health. The slightest mistake can result in numerous errors and ultimately cause a project to be extended or put on hold. That’s why working with code may be associated with individualism, and cause the programmer to be perceived as a lonely scientist who spends a lot of time solving intricate programming problems alone. Meanwhile, working on code is largely a heavily collaborative effort between many engineers. The completion is possible only if each one of them understands every part of the project. So the easier to read and understand the code, the better.

Programmers spend a large portion of their time reading code that has been written by someone else. To make the right interpretation of such a code, they need to make sure they understand what the author wanted to convey. Usually, it’s much harder if what you made is not readable. That's why at Accesto we stick to CLEAN CODE principles.

What is Clean Code?

Grady Booch, editor of Software Development magazine, once said that clean code reads like well-written prose. And as we know, any written form must have a definite, readable and understandable structure in order to be read well. Otherwise, readers may conclude that the work was written by someone who doesn't know the subject or someone who doesn't care. It is the same with programming. If we want our audience, which are other programmers, to be able to read our code, we should follow certain rules. These rules are of course called CLEAN CODE.

So what is CLEAN CODE? The most well-known definition comes from Robert C. Martin (aka. Uncle Bob) who wrote:

„Clean code is code that is easy to understand and easy to change”

But what does it mean exactly? In short, it means your code should be readable, easy to understand, and allow for easy changes. You can achieve this result if you stick to few rules and common good practices. Among others (as there are many), there are two sensible and simple:

• DRY = Don't Repeat Yourself
• KISS = Keep It Simple Stupid

These two principles help you write code in such a way that you or other programmers can read it and understand its logic without guessing. It simply means that you will always consider whether there is a better way to solve problems in your code. But these are just an exmaples of many popular acronyms, like SOLID or GRASP, that stand for a large set of common good practices that every professional software developer should be familiar with. These all deserve separate articles perhaps, but today, I will focus on 7 particular ideas that you can follow every day. Like rules of thumb that will help you to achieve and maintain better code readability on a daily basis.

Why is it important to write a clean code?

1. Once we understand the structure of the code, it is easier to fix any bugs in the future.
2. Readable code greatly decreases the time it takes to write anything new.
3. Creating readable code translates into how you feel about it because you can be proud of your work.
4. Incorporating clean code into your existing projects will let you see a difference in the quality of your work.
5. Avoiding code that makes people feel confused creates less technical debt in projects.
6. If you don’t make your code clean, you won’t have much time to correct it later, and it will definitely backfire.
7. Your code represents you, so in the future, when you meet your colleagues again on another project, the quality of your work may affect whether your colleagues will be open to working with you and your code.

Still not convinced? So let's talk about money 💸 Have you ever thought about how much money you actually lose with bad code? If you haven’t, you can read more about this in article written by our CTO: <a href="https://accesto.com/blog/how-much-money-you-lose-with-bad-code/"target="_blank">How much money you lose with bad code.

Writing clean code - 7 useful ideas for readable code

But how can we make our code readable? It's worth remembering a few important rules so that both you and others on your team can easily interpret the code and work on it.

1. Think about other people in your team

Yes, that's true. While coding, you shall not only think about the code, but should also think about the others. When we work alone on a project, we may feel that the most important thing is to make the code understandable only to us. After all, who else might sit down and need to use what we wrote. Remember, however, that at any time there may be a situation in which someone else will need to look at our code and make changes there. Even if you're a one-man Army programmer at first, that can always change, and it's worth accepting that in some time someone else may gain access to your code. Therefore, it is a good idea to write code with the assumption that someone else WILL use it. Even it you think than noone will ever do it. Create it in such a way that all the rules related to Clean Code are kept. To make sure that our code is readable by other people, we can also show what we created to other people and ask them to check its readability. Remember that we are not infallible, and other people can point out what we have missed.

2. Make reusable code and avoid copy-pasting

Is writing the same code several times over the course of one project a good idea? No, the best way is to write the function once and then use it several times in the project. This simply saves time and also makes other people see some repetitive pattern in it, which of course makes it easier for them to understand what the author wanted to create. Although it may be tempting to just copy & and paste the code, this only increases the <a href="https://accesto.com/blog/technical-debt-the-silent-villain-of-web-development/ "target="_blank">technical debt and converst your code info maintenance nightmare.

Reuse functions instead of copying blocks of code

In 1999, Andy Hunt and Dave Thomas wrote a book called The Pragmatic Programmer, in which they described the DRY (Don't Repeat Yourself) principle. This is a very well-known concept, according to which programmers should avoid repetitive patterns and build code in such a way as to be transparent to others.

3. Leave your code a bit better than you found it

Or in other words - be a good Boy Scout. As Boy Scouts try to leave the campground cleaner than they found it. And you should think the same about the code. Always try to transform bad code you see, into something better. But watch out! As our senior dev Michal mentioned in his great arricle on Boy Scout rule in PHP, you should focus on the campground, not the entire forest! Over-refacotring is a common anti-pattern may make things worse.

4. Keep your modules, classes, and fuctions small

Have you ever heard that small is beautiful? It's especiall true when it comes to...code 😉 Size may be something that differentiates good and bad code. Some people tend to create large pieces of code that that are generic, robust, flexible and... unreadable. Meanwhile, it is way easier to test, analyze and maintain smaller pieces of code. In short, to write good code you should keep it digestive. Therefore, it is a good idea to break down parts of the project into smaller components, classes, and modules, which increases readability and contributes to the fact that it is simply easier for other people to work with our code. Reading hundreds of lines of a complex code logic can be a true nightmare. That's why a good software craftsman write functions that are small and easy to read at once. Usually many small functions are better than a few but large ones - you can use it as a rule of thumb.

Source: pragprog.com

5. Maintain a consistent code style

Here, a good analogy is writing a book. World bestselling authors are masters at creating and using their style, which not only allows them to stand out from other authors, but also allows them to draw the reader in and keep their attention. If an author changed his style several times in his book, he might introduce dissonance in the reader. The same is true with writing code. To write clean code it is very important to format code in a consistent way. Not having a specific style for formatting code can cause someone who uses what you've created to have to guess what the changes are for. This, in turn, can lengthen the process. Consistency in style allows others to avoid confusion.

What you can do is implement style automation for your code. EditorConfig can help you with this. It is a solution that allows you to configure and use the same code style and formatting style to achieve the right level of readability.

More details on editorconfig.org

The way it works is that you insert an .editorconfig file into the root directory of your project. The editor in turn pulls this in and uses the rules created on the files. 

6. Trust your feelings about the code

How you feel about the code also matters. If you recognize that the code may be highly complex, it's worthwhile for you to consult other team members to gain a fresh perspective. Then you can revisit the entire process and think about where improvements are worth making. Usually if you smell that something is wrong with your code, you are right, and don't ignore that smell.

7. Use a second pair of eyes

Last but not least - code review. The only way to check if you actually produce readable code is to let someone else read it. It is hard to overstate the the power of peer code review. And you shall practice it whenever possible. If you use comments or provide any other explanation to developer reviewing your code, it already indicates poor readability. A second pair of eyes reading your source code is the best check of code's readability. Period.

100% clean code?

Being a software developer poses numerous problems and requires you to constantly think about the fact that there is always room for improvement. An essential part of expanding your coding skills is understanding that you often won't write 100% perfect code right away. There is nothing wrong with that. Making mistakes, correcting them, and then making improvements to eliminate the same mistakes in the future are a natural part of developing knowledge and experience. When you know something might not work, making improvements will allow you to enjoy better collaboration, reduced development time, and less debugging pain. Focusing on creating clean and understandable code is one of the most important factors that will help you achieve these results.

Tired of poorly written code?

Are you passionte about code quality? We do! But we also love sports, travel and well being. At Accesto you can master your software craftsmenship together with people passionate about code and life - equally.

Join us at: https://accesto.com/career/