😰 ✅ 🖕 How to read and fix 100,000 lines of code per week ☝🏼 🍿 🕵🏾

In the beginning, it’s always hard to figure out the big and old project. Architecture assessment is one of the activities of the architect. Usually you have to work with large, old projects, and the results must be provided in a week.

How to evaluate a project with a size of 100k or more lines of code per week while providing really useful results for the client.

Most architects and those leads have come across similar project evaluations. It may look like a semi-formal process or as a separate service as it is done in our company, anyway most of you have dealt with this.

The original English for your non-Russian-speaking friends is here: Architecture Assessment in a week .

The approach in our company

I will tell you how it works in our company and how I act in such situations, but you can easily change this approach according to the needs of your project and company.

There are two flavors of architecture assessment.

Internal - we usually do it for projects within the company. Any project can request an architecture assessment for several reasons:

The team thinks that their project is perfect and this is suspicious. We had such cases and often in such projects everything is far from perfect.
The team wants to test their project and their decisions.
The team knows that everything is bad. They may even list the main problems and causes, but they want a complete list of problems and recommendations for improving the project.

External is a more formal process than internal evaluation. A client always comes only in one case when everything is bad - very bad. Usually, the client understands that there are global problems, but cannot correctly determine the causes and break them down into components.

Assessing the architecture for an external client is a more complex case. The process should be more formal. Projects are always big and old. They have a lot of problems, bugs and crooked code. A report on the work done should be ready within a few weeks maximum, where there should be the main problems and recommendations for improvement. Therefore, if we deal with the external evaluation of the project, then internal it will be a couple of nonsense. Consider the most difficult case.

Assessment of the architecture of an enterprise project

A typical project for evaluation is a large, old, enterprise project with a lot of problems. A client comes to us and asks to fix his project. It's like with an iceberg, the client sees only the tip of his problems and does not know what is under water (in the back of the code).

Problems that the client can complain about and may know about them:

Performance issues
Usability Issues
Long Deployment
Lack of unit and other tests

Problems that the client most likely is not aware of, but they may be present in the project:

Safety problems
Design issues
Incorrect architecture
Algorithmic Errors
Inappropriate technology
Technical debt
Invalid development process

Formal Architecture Assessment Process

This is a formal process that we adhere to in the company, but you can adjust it for yourself depending on your company and project.

Customer Request

The client asks to evaluate the architecture of the current project. The responsible person on our part collects basic information about the project and selects the necessary experts. Depending on the project, these may be different experts.

Solution Architect is the main person responsible for evaluation and coordination (and often the only one).
Stack specific experts - .Net, Java, Python, and other technical experts depending on the project and
Cloud experts technologies - these can be Azure, GCP or AWS cloud architects.
Infrastructure - DevOps, System administrator, etc.
Other experts are big data, machine learning, performance engineer, security expert, QA lead.

Project Information Collection

You should collect as much information as possible about the project. You can use different techniques depending on the situation:

Questionnaires and other means of communication through mail. The most inefficient way.
Online meetings.
Special tools for exchanging information such as: Google doc, Confluence, repositories, etc.
“Live” meetings in place. The most effective and most expensive way.

What should be received from the client?

Basic information. What is the project about? Its purpose and value. The main goals and plans for the future. Business goals and strategies. The main problems and the desired result.

Information about the project . Technological stack, frameworks, programming languages. On-premise or cloud deployment. If the project is in the cloud, what services are used. What architectural and design patterns were used.

Not functional requirements . All requirements related to performance, availability, usability of the system. Security Requirements, etc.

Basic juskeys and data streams.

Access to the source code . The most important part! You should definitely get access to repositories and documentation on how to assemble a project.

Access to infrastructure . It would be nice to get access to the stage or production infrastructure in order to work with a live system. This is a great success if the client has tools for monitoring infrastructure and productivity. We will talk about these tools in the next section.

Documentation . If the client has documentation, this is a good start. It may be outdated, but it's still a good start. Never believe the documentation - check it with the client, on a real infrastructure and in the source code.

Architecture Assessment Process

How, then, to process such a large amount of information in such a short time? First of all, parallelize the work.

DevOps should look into the infrastructure. Those lead into the code. Performance engineer see performance metrics. A database specialist should dig deeper into data structures.

But this is an ideal case when you have a lot of resources. Typically, a project is evaluated by one to three people. You can even conduct an assessment yourself, which often happens if you have the proper knowledge and experience in all areas of the project. In this case, you need to automate all the processes as much as possible.

Unfortunately, you will have to read the documentation manually. With the proper experience, you can quickly understand the quality of the documentation. What is true there and what clearly does not coincide with reality. Sometimes you may find such an architecture in documentation that will never work in real life. This is a trigger for you to think about, but how is it done in reality in the project.

Useful tools to automate project evaluation

Evaluating a code is a simple exercise. You can use static code analyzers to show design, performance, and security issues. Here are a few of them:

Structure 101 is a great tool for an architect. It will show you the big picture, the relationship between the modules and the potential areas for refactoring. Like all good tools, it costs a lot of money, at the same time you can use the trial 30-day version.

SonarQube is a good old tool. Tool for static code analysis. Allows you to identify bad code, bugs, security problems for more than 20 programming languages.

All cloud providers have infrastructure monitoring tools. This will allow you to correctly evaluate the effectiveness of the infrastructure in terms of cost and performance. For AWS, this is a trusted advisor . For Azure, it's just an Azure Advisor .

Additional performance monitoring and logging can help you find performance issues at all levels. Starting from a database with inefficient queries, a backend and ending with a frontend. Even if the client has not installed these tools before, you can quickly integrate them into your existing system to identify performance issues.

As always, good tools are well worth it. I can recommend a couple of paid tools. Of course, you can use open-source but you will need more time for this. And this should be done in advance, and not in the process of evaluating the architecture.

New Relic - application performance evaluation tool
Datadog - cloud-based sister monitoring service

There are many tools for security testing. This time I will recommend you a free system scan tool.

OWASP ZAP is a tool for scanning web applications for compliance with security standards.

Putting it all together.

We are preparing a report

Start your report with customer data. Describe the objectives of the project, limitations, non-functional requirements. After this, all incoming data should be mentioned source code, documentation, infrastructure.

The next step. List all problems that you have found manually or using automated tools. Place large auto-generated reports at the end in the application section. Here should be short and succinct evidence of the problems found.
Prioritize the problems found on the error, warning, info scale. You can choose your own scale, but this is generally accepted.

As a true architect, you must provide recommendations on how to fix the problems you have found. Describe the improvements and value to the business that the customer will receive. How to show business value fromarchitecture refactoring we discussed earlier.

Prepare a roadmap with small iterations. Each iteration should contain time for execution, description, amount of resources needed for improvement, technical value and value for business.

We finish the architecture assessment and provide the client with a report

Never just send a report by mail. It may or may not be read at all or read and not understood without proper explanation. In short - live communication helps eliminate misunderstandings between people. You should set up a meeting with the client and talk about the problems found, focusing on the most significant. It is worth paying the attention of the client to problems about which he might not even suspect. Such as security issues and explain how they can affect a business. Show your roadmap with improvements and discuss different options that are more suitable for the client. It can be time, resources, amount of work.

As a summary of your rally, send your report to the client.

Finally

Assessing architecture is a complex process. To conduct an assessment properly you need to have enough experience and knowledge.

It is real - to provide the client with useful results for him and his business in just a week. Even if you do it alone.

Based on my experience, many improvements were downloaded in the middle, and sometimes never started. Those who chose a middle ground for themselves and made only part of the improvements that were most useful for business with minimal labor, significantly improved the quality of their product. Those who did nothing after a couple of years could completely close the project.

Your goal is to show the client maximum improvement at the lowest price.

Other articles from the architecture section can be read at your leisure.

I wish you clean code and good architectural solutions.

Our facebook group is Software Architecture and Development .

How to read and fix 100,000 lines of code per week