Legacy application code review - Part 1: The big picture

This post is the first part in a series about what to look for when inheriting a legacy code base. This post will focus on looking at the big picture of the application and how the system fits together.

Legacy code bases get a bad rap, but they can be just as fun of a puzzle to solve, if not more fun, than working from a clean slate. Not only do you have to make decisions that are flexible and extensible in the long-term, but you do that within the delicate balancing act of not breaking what is already there.

Since there are way more dependencies and considerations to take into account when working with an existing application, I recommend doing a full code review and audit of the application before creating any estimates or making any plans for future functionality. Having as much knowledge as possible will help you make informed and robust decisions about the best path forward.

In this post, I outline a variety of things I recommend investigating during this code review, what we learn from those findings, and how to adjust your recommendations and estimates.

Does it run?

Before you begin your code review, the very first thing to try is to run the application locally. This is important, because if youre unable to get the application running within an hour or two there may be a bigger issue hiding. And its not worth your valuable time to debug setup issues.

If you cant get the code running following the documented steps or standard industry practices, reach out to your stakeholders or previous developers if possible. If the answer is that the code doesnt run, then you should start having a larger conversation about the work it will take to stabilize the development environment before even considering trying to estimate future functionality. Its not prudent to estimate how much it will cost to build an addition on a house when the foundation is crumbling.

Language/framework audit

Once you have the code base running, check the language and framework version(s) of the application to determine its current support status. Running old versions of languages and frameworks can open the application up to unfixable bugs or unpatched security vulnerabilities. Using out-of-date versions may also limit your ability to deliver on your stakeholders big ideas if they want modern features that arent possible with the old framework version they have.

In most cases, maintainers will deprecate older versions and no longer release updates after a certain date. And whether or not open source, these support timelines and policies are usually published publicly so you can plan your upgrades to stay ahead of deprecation and EOL (end of life).

For example, heres a sample of open source and proprietary languages and frameworks just to give you an idea of what to expect.

• Ruby
• Node
• React
• .NET

Infrastructure audit

After you audit the backbone of the application, look at the supporting infrastructure to catalog the versions, support, and necessary dependencies. Pay special attention to the database (the powerhouse of an application) but also look at other infrastructure driving the application such as storage services, caches, message brokers, etc. As before, you are auditing version support and if the infrastructure is currently supported.

While its not required, I recommend drawing a diagram for yourself and your stakeholders showing how these pieces fit together. This is a brilliant place to add value as an engineer because often, no one understands the complete picture.

A diagram can help you technically by serving as a reference to the architecture of the system when you need to evaluate future services to integrate with. And it can help your stakeholders gain an awareness of the complexity of their system, which helps form useful context when you propose a higher than expected estimate. Sometimes theres even an added, immediate benefit of eliminating overhead by showing them they have unused services they are paying for that can be stopped!

While evaluating the infrastructure, also make note of any interesting dependencies and considerations. For example, if you discover an Oracle database hooked up to the Rails app, do a little extra research to look into the ActiveRecord adapter for Oracle and document any limitations since Oracle isnt a standard choice for a Rails app.

By paying attention to what infrastructure is there and how its configured, you can note any architectural considerations you may have when estimating and planning your project.

Environment audit

The next step in your code review journey is to learn about the various configured environments and their automated continuous integration and continue delivery (CI/CD) pipelines or lack thereof. Understanding the environments and how they fit together is key to planning your developer workflow and productivity and determining quality assurance (QA) and user acceptance testing (UAT) processes.

If there are no automated CI/CD pipelines configured, include time for setting those up in any estimate you provide. Automated CI/CD pipelines increase developer productivity by automating tedious parts of your work, decrease broken builds/deployments which limits regressions, increase code quality by enforcing that your code meets certain criteria before being deployed, and shortens time to market for your stakeholders by making it easier to deploy code early and often.

Data model and database design

Its helpful to understand the project domain youll be working in by looking at the database and the relationships between the data models. Pay attention to how normalized the data is. Normalized data limits data redundancy. For most standard use cases, we want normalized data. If you find that the foreign key or association path to any single model in your database follows many routes, you have denormalized data.

There are tools out there that will generate an ERD (entity-relationship diagram) to make it easy to see these relationships. This is another place where you can start providing immediate value to your stakeholder if they do not already have their data relationships documented.

I like dbdiagram.io which lets you upload a variety of schema files and auto-generates a diagram for you. dbdiagram.io requires that your relationships are modeled in the database layer. If you find that most of your relationships are only modeled at the application layer (Ive seen this happen in many Rails projects), you may need a different tool such as rails-erd, which will generate a diagram based on the ActiveRecord associations present in your code.

This is an example of denormalized relationships, notice how many direct and indirect associations there are for the same relationships.

This is an example of mostly the same tables after they've been normalized. There are many fewer associations duplicating the same relationships.

You should also pay attention to what data constraints and validations are present. A strong combination of normalization and constraints protect the data from anomalies during insertion, update, and deletion that can introduce bugs into your application from out of sync relationships or mismatched data that is duplicated in multiple places.

A database that is very denormalized or lacks constraints such as foreign keys or not nullable constraints informs you to plan time for remediating these concerns before adding new features. If you cannot make changes in the database, increase your estimate to allow yourself more time to write extra robust validation and error handling code. Youll need to proactively prevent dirty data that could cause hard to find application bugs.

Conclusion

Understanding the various components of a system besides the application code, can help you understand the big picture and start to form system-level and architectural-level recommendations for your stakeholders. In the next post, we'll leave the big picture behind and dig into reviewing the application code itself.

Existing application code review checklist

1. Does it run?
2. Language/framework version support
3. Infrastructure version support - database, storage service, cache, message broker, etc.
4. Configured environments
5. CI/CD pipeline
6. Data model
7. Static analysis
   1. Code base size
   2. Class and method size
   3. Cyclomatic complexity
   4. Churn
   5. Test coverage
8. Human analysis
   1. Security audit
   2. Code conventions and idioms
   3. Dead code
   4. Dependencies
   5. Documentation
9. Dynamic analysis
   1. Performance profiling