Five Ways to Improve the Understandability of your Software

As developers, we all understand that we spend too much time trying to understand our own code and its behavior. This gets even trickier when we are trying to understand someone else’s code, perhaps written a long time ago by a person who’s left the org. 

The traditional ways to deal with this problem are less than ideal, writing endless log lines, and waiting for long re-deploys to get the data we need. Many times, the better option is simply to move forward with limited data, because it’s not worth the time and effort. But in a data-driven world, having the right data when you need it can make or break your business.

So let’s look at some ways we can improve the understandability of our software.

Tackle Complexity

The most straightforward, though sometimes most difficult, approach to maximizing understandability is avoiding complexity. When developing a new application, it’s imperative to have a clear understanding of the problem domain and the issue you are trying to solve. The simpler and more focused the business requirements are, the less complex the solution is going to be. 

Additionally, there are many rules of thumb you can follow to minimize complexity in the implementation phase:

1. Use a highly-skilled workforce to carry out the work the best way possible.

2. Select the highest-level building blocks you have available to build your application on. This not only includes development languages, but also databases, cloud providers, and other third-party services.

3. Apply software engineering principles to minimize complexity.

4. Develop in an Agile manner, doing things step-by-step, and avoid over-engineering.

Unfortunately, when working with a predefined team on an existing application, you don’t have as much flexibility to make your own choices. Over time, you should strive to hire and train the best people and adopt the best tools, techniques, and processes in the market. And yet, these processes will take a very long time, and the impact on complexity and Understandability may only become apparent in the distant future.

Documentation and Knowledge Sharing

When dealing with a complex system, it’s crucial to build a shared understanding of it. Somebody out there might have some understanding of that system — maybe multiple folks, each with their own perspective that can help you make heads from tails. Having good documentation will save yourself and others from repeated headaches.

And even if nobody truly understands what’s going on, you are probably uncovering glimpses of the truth every day. By collecting that information and distilling it into your tomes of knowledge, you make the system that much more digestible for everyone involved.

Start out by tasking an engineer (or team) with curating that knowledge. Make sure they have a good understanding of both the business domain and the technical stack involved. Have them go through existing documentation and weed out the truth from the lies. Where documentation is missing or misleading, and it often is, search for insights among current and existing team members. Many former employees would be happy to have a (virtual) coffee to discuss their past work and help share some of their knowledge (remember to properly thank them for the effort and avoid abusing their time!).

Whether you prefer articles in a shared Wiki or documents stored online, make sure to have something in place for centralizing the knowledge. As always, a picture may be worth a thousand words, so creating architecture diagrams and flow-charts is time well spent. Besides granting everyone access to it, giving the occasional session can go a long way in getting the team up to speed on the way things actually work.

Better Development Environments

If you want to understand something, breaking it apart and putting it back together is often the way to go (lucky for us software engineers, if we fail to put it back together we can just revert!). 

This means you have to make sure your engineers have an environment where they can run the code they are writing, test it with different inputs, and even debug it. 

This is often trickier than it sounds as environments tend to drift apart, production data might be restricted to that environment, and network traffic might be difficult to simulate. And yet, by building your engineers a great sandbox, you’ll definitely enable them to study the application more efficiently.

It’s also worth noting that in certain environments such as Service-Meshes, Serverless, and even large monolith applications, connecting a traditional debugger might be a very complex task.

Observability Tools

Observability tools are designed to allow Site Reliability Engineers (SREs) and other engineers to get a glimpse into the state of production systems from the outside. This is usually done in the form of logging, metrics, tracing, and service maps.

If your organization has those tools in place, they can often provide you with some glimpse into the system’s behavior. This glimpse, however, can be somewhat limited as Observability tools can only automatically instrument generic code. To look deeper into your business logic you must add more loglines/metrics/traces via code.

Keep in mind that overly relying on Observability tools to achieve Understandability usually results in logging FOMO, where engineers try (and fail) to record everything potential piece of data for future use.

Understandability Tools

Often, the most surefire way to improve your team’s Understandability is deploying production-debuggers. This new breed of tools allows engineers to set non-breaking breakpoints in any line of code in any environment, to instantly see the full application state.

By seeing into the code in the relevant environments, engineers can quickly investigate the inner workings of the application. Whether it’s viewing the runtime types and values of variables or noting why a function is being invoked and with what arguments, the necessary data can be collected within seconds.

Summary

Understandability is a term taken from the finance industry and applied to software. It’s a natural evolution from Observability, and when taken seriously can save developers countless wasted hours. There are things you can do today that require no tooling: if you’re building a new application, prioritize simplicity from the beginning. Make sure to have some sort of knowledge sharing process in place, where everyone across the org can update documentation that can be helpful to someone else in the future. And by creating better dev/staging environments, you’ll be able to understand your code much more efficiently before it goes live in production. To go to the next level, invest in best-of-breed Observability and Understandability tooling.