The Importance of Writing Clean Code

GitLab sponsored this post.

In the financial industry, understandability is the concept that information should be presented in a way that makes it quick and easy for a reader to understand. To be understandable, a financial system needs to be complete, concise, clear and organized.

The concept of understandability needs to be brought to the software world.

We’ve seen that the rise of microservices, cloud and distributed systems have all added to the complexity of modern systems. This means that our development teams have to work even harder to efficiently build applications that can easily be maintained by an ever-growing number of developers.

How We Write Code

Understandability starts with how we write our code. As developers, it’s crucial to invest time in refactoring, in order to make sure the code we are writing is easily digestible by our colleagues; as well as by the programmers who will end up debugging our code next month, next year, or even ten years from now. On top of that, change requests should only be approved if inline comments and external documentation are complete, concise, clear and organized.

• Complete: Contains all the information that a developer would need in order to understand the expected behavior of a certain component.
• Concise: Written in a way that is easily scanned for highlights, and is not too cumbersome or repetitive; in a way that contains the relevant information, and not too much else.
• Clear: The format and medium are easy to scan. In the world of software development, this usually translates to inline comments and wiki pages.
• Organized: The information is presented in a way that makes it easy for the reader to cross-reference information. A well-maintained wiki page, or an integration with an IntelliSense tool or a source control management tool, usually do the trick here.

Spending time on documentation and comments may appear to slow down the development of a certain feature. But as someone once said, if you have six hours to chop down a tree, it’s wise to spend the first four sharpening the axe. The upfront effort will make our applications much easier to debug and maintain in the future. Because when applications become too buggy, too hard to support, and when handoffs become too time-consuming and ineffective, then we end up spending entire sprints on improving documentation, unit testing, logging and more.

In the complex world of microservices and distributed systems, where developers spend 10 times more time reading code than they spend writing code, it’s more important than ever that the code we are writing is clean and easy to communicate to others.

After the Code is Deployed

Even if you’ve written clean and well-documented code, in the world of cloud and distributed systems it’s still hard to predict how that code will behave after it’s deployed. Think of clean code like a good cooking recipe: it clearly lays out what should happen and you will refer back to the recipe often during the preparation of the meal, but the recipe cannot possibly know the current temperature of your oven or how you’ve mixed the ingredients.

To make our applications truly understandable, we have to be able to observe our code in real-time. Tools such as Logging, Tracing, Monitoring, Error Tracing and Profiling tell us how the application is actually behaving when the code is running. This is just as important as writing clean code in the first place, because while reading the code in its static state is crucial for understanding the application, we also know that it can never provide a full representation of how the application actually behaves in production.

A great example of this is configurations. If you have code with a big switch-case that is based on a configuration, then simply reading the code will only tell you what is possible. To know what is actually happening, you have to understand the configurations that are being used at runtime.

And remember, at the end of the day the goal is to actually go beyond observing our systems and get to a place where we truly understand them. That means we need tools that integrate into our development environments, that retrieve data in the context of the written code, and that provide a deep and dynamic view of how the code behaves in the real world.

Most companies are not there yet. If you have Observability in place, you are already ahead of most. But after observing a problem, there’s still additional work necessary to actually drill in and figure out what’s going on within the application. Production debuggers are a great example of tools that are addressing the problem of Understandability, and I foresee this category becoming more and more discussed in the coming months.

Feature image via Pixabay.

At this time, The New Stack does not allow comments directly on this website. We invite all readers who wish to discuss a story to visit us on Twitter or Facebook. We also welcome your news tips and feedback via email: feedback@thenewstack.io.