The Importance Of Writing Readable Code

Welcome, today’s discussion is going to be about the importance of writing readable code. We will be focusing on what is readable code. Why do we need it? What are some of its benefits of it? and essentially, how do we write it? Focusing primarily on the first two but covering all of them from different angles.

What is readable code?

Readable code is simply code that communicates its intent to the reader. It means that when you pull up some code or any type of software, (be it HTML, Java, C, .Net, whatever) that anyone can look at the code and you understand what the code is doing.

Benefits of using readable code

Easier for us to understand what the code is doing. The intent is for any developer to come in, open the code, look at the code and understand what’s going on.
Clean and easy to read it make it easier to understand how the code works. When code is written cleanly, it beings to self-document the requirements. If done right anyone can come behind the coder, and easily make a code modification or fix a problem.
Makes it easier for us to write testable code, like unit testing. Because if the code is written cleanly then the functionality of our functions, methods, etc… are easier to understand. Such that a tester should be able to identify how the code works, making it easier to test them.

Additionally, some other benefits are taking existing documentation such as software documentation and requirement documentation, and taking pieces of this documentation and putting it in the code where it belongs. So, we know that this code goes with this functionality or this requirement.

What happens when we don’t write readable code?

Hard to understand.
Complex code can be hard to read.
Hard for other developers to follow the developer’s intent because it is not clear.
No idea or understanding of how the code works.

Typically, when we don’t write readable code, you’ll hear developers say, oh, the code’s unmaintainable it’s spaghetti code. We don’t know what’s going on. Those are signs that your code is not readable. It was not written well. It’s also very hard to make code modifications or fix a problem because the code is unreadable or unmanageable. You don’t know what’s going on or where to begin. Simply put, if you don’t know what’s going on with the code and you can’t read it, you can get stuck.

The same thing applies to testing. If the code is unreadable, you don’t know where to test it. You don’t know how to test or where to test a feature in the software.

How do we write readable code?

There are essentially four ways you can write readable code, but really there are five.

Documentation
Code Standards
Style Guides
Code Reviews
Practice

Documentation

Begin with some clear type of documentation. These can be either software requirements, specification documents, some type of test plan, or some other type of business requirements. Essentially, you want some type of documentation around the software that you are going to be writing or changing. So, documentation is really key for writing well-documented readable code.

However, so many companies and so many organizations skip this step for very small module pieces. Requirements in smaller tickets, they give you smaller chunks and we don’t have that large document giving us a big overview of how our software works. So, documentation is key. The other thing for documentation to think about is whether you’re writing a message to your future self with this documentation or a future developer.

Coding Standards

Coding standards define how we are going to write our code. Such as, what are the different requirements based on things like our language, environment, architecture, or other significant coding considerations that we should follow. Especially, when we bring in a new developer, making it easier for the new developer to jump in knowing how to write the code, and what to expect when they’re looking at the code. Because everyone is following the same template as they’re writing their code.

Style Guides

Style guides are the way you should organize your code, name variables, name methods, and define classes. Anything that pertains to your language’s basic coding standards, basic style guides, and file naming conventions. For example, in Java, there are specific industry standards around how you name your classes, the way you name your methods or your functions, or the way you name your CSS files.

Code reviews

Code reviews, help in a couple of different ways. One, it helps maintain readability because if someone else reviews it and they can’t understand it, or they can’t read it or they can’t follow it, then it probably needs to go back and be refactored and cleaned up so that it can be understandable.

This also helps flush out any potential logical problems or potential bugs that could be introduced into an application. Something that maybe the tester or the developer forgot to test, or they didn’t think about a particular edge case. These are things that you can look at with or catch what code reviews and code reviews are also a good place to help make ensure that you’re following those coding standards and style guides.

Practice

Finally, we have practice. Unfortunately, this is not something that can be easily done overnight. It takes a lot of time and a lot of practice to get good at writing readable code. Typically, a lot of students come out of college following the examples and derivatives that they were taught in school. They will have one mindset of what coding standards or coding styles are based on whoever taught them.

For example. say you bring five students into one organization from different colleges. Every single one may have its own styling technique. So, for everyone to get on the same page, they need to start learning the coding standard. They need to learn the style guides and the only way to learn this and implement them is to practice. By repeatedly doing it again and again, then follow up with code reviews. Make sure that the code reviews are a team exercise and the code meets with the style guides, and the coding standards, all the way back up to the required documentation.

Practical Demo

In the rest of the video we walk through a simple real-world code example, but it really drives home what readable code is and how to make it work.