Software architecture

In this article, I would like to show you five challenges faced by teams implementing software:

• maintainability

• scalability

• testability

• readability

• performance

---

Why code quality is important

Each project is easy and understandable for everyone (at the beginning) Then developers make various decisions that affect code quality.

At the beginning of a project, usually, people are happy, and the work goes smoothly. With time, the pace slows down, and the smile disappears.

• knock knock

• who’s there?

• technical debt

In the end, developers are frustrated, and project owners are as well. Where did we go wrong? People ask.

This story shows why code quality is important. Quality does not only affect how the application works. Of course, low-quality code causes problems with, e.g., performance.

In addition, bad code slows down product development in the long-term, makes developers dissatisfied, as a result of which they often change jobs, and it’s hard to find others in their place because no one wants to work with technological debt.

---

Five major challenges developers face

I’ve identified five challenges developers have faced during the development phase. If you do not care for these things, your project will become a monster everyone runs away from. Keeping the challenges at the forefront is an effective way to save you energy and time while developing your app.

Maintainability

The difficulty of maintaining the project depends on the number of developers. It’s not a big deal to manage the quality of the code when you have two devs in the project (but it can still be). In large projects, you need an experienced technical leader and/or architect to be sure that the project meets the functional and non-functional requirements and that the technical debt does not increase overnight.

Architect’s role

The architect’s role is especially important at the beginning of the project (before the coding phase as well). Architects are usually people with a wide range of skills, from frontend/backend, through testing, DevOps to infrastructure.

Their task at the beginning is to collect requirements, high-level estimation, and develop a delivery plan, including determining what people are needed for the project. In addition, architects are also responsible for designing the architecture for the given requirements.

In addition, architects often start a project, i.e., prepare a development environment, CI / CD pipelines, checks, and proof of concepts of some parts of applications.

Of course, architects often consult their ideas with other specialists such as dev ops engineers, backend developers, QA specialists, and so on.

Are architects really needed?

You may ask why I am writing now about an architect in the context of project maintenance.

It turns out that large projects that could not count on the architect’s support at the very beginning of the work often ended with either a failure or a huge technological debt. One of the most common mistakes when implementing a project is starting development without analysis, architecture, in progress, or too fast.

Once the project has started, the architect is still in the project and directly teaches the team how to create the code and, together with the team leader or engineering manager, works out the development process. With time, the architect’s commitment decreases as the team is fully competent and can produce and maintain the code later.

Scalability

The problem is the same as maintainability. Generally speaking, it is applicable across all software applications as well. I do know that the art of making good code can also take more than just good design.

Oftentimes, a small-scale MVP is done to test the idea.

When a project is already used by users, it often turns out that it needs to be scaled so that:

• handle more users

• more traffic

• add new features

• integrate the project with other systems

This often involves rewriting, refactoring, adding new code, and big changes in general.

At this point, again, many mistakes can be made, which can spoil the project. It is a good idea to increase the role of the architect to help developers face new challenges.

Testability

I often heard that “we do not write tests because now we do not have time for it, and we will add them later”

This approach creates a great risk because testing the code is not so simple that you take every component and function and just test it.

Testable/untestable components

When you don’t think about tests while writing your code, you often create untestable components because they are written so that they cannot be tested and need to be refactored.

Leaving testing at the end makes you end up with a base of components/functions/code that cannot be tested. So, technological debt again.

Fitness functional testing

Another aspect of testing is measuring whether the project architecture meets the given requirements. For example, the requirement that the web project must meet Google Core Vitals, or the website will load on mobile devices in 1s.

You can implement fitness functions that measure it, and you have to measure it from the beginning of the project, not, e.g., three months after launch.

Bottom line: don’t leave the tests for the very end.

---

Readability

What does readability mean? The code itself can be readable or unreadable, but that is often an opinion.

Automated tools

Fortunately, there are tools that allow you to check code quality and readability (for example, the Sonar cloud). Such tools give no opinion; they test the code based on a given configuration and show if it is classified as good.

Unfortunately, you can write garbled and bad code without this tool showing you anything. it is possible. So what can we do to improve the readability of the code?

I don’t want to go very deep into the code here, but I would like to highlight three important points:

Comments

Short and clear what the more difficult parts of the code do

Documentation

A high-level description of what the code does and what it does. Graphs work well because it’s easier for people to understand a picture than a text

Tests

The tested code is more understandable because the test allows you to read what the code does. I have seen cases where the test replaced the documentation, and the code was understandable

Performance

Application performance is very important these days, and it doesn’t matter what system you do. In the end, there is a user who expects something to work very fast.

Performance is often a trade-off. You have to give up something for the application to run faster.

Performance is often looking for non-obvious solutions, hacks in the code that affect all the above-mentioned areas, i.e., maintainability, scalability, testability, and readability.

Therefore, taking care of performance is a constant and very important process in software development that cannot be ignored.

---

Tools to review code quality

Automated tools

Most Devs already use Git to manage their repository and have become accustomed to using pull requests for reviews. It’s also very possible to automate code reviews using several tools. Security considerations should also be noted in coding quality. Code quality and security are the same with static analysis enabling detection of either kind of problem. Typically developers utilize static analysis techniques to construct and test component designs and software.

It is important to ensure that all tools are correctly configured and connected to the pull request.

Code reviews

Once the static code analysis is done, and all checks/builds are “green,” it’s time for a human review of the code.

I believe that you should not check the code that does not pass the first stage mentioned above because it means that the code already has some problems that the machine has detected, and it is not worth even wasting human time looking at it.

Doing code reviews is certainly a topic for a separate article. The most important thing is to check what static code analysis cannot check, e.g.

• is the code compatible with the architecture

• if there are no hacks in it

• is it human-readable?

• whether it meets the business requirements

---

Conclusion

Code quality is important to both developers and product owners. Good quality code is easier to maintain and develop.

Readability, tests, and documentation significantly affect the quality of the code and the product as a whole, and thus the satisfaction with the work of team members, and finally, end users who use the product.

The quality of the code can be measured thanks to automatic tools such as GitHub actions, Sonar cloud, and thanks to human review of the code.