What Are the Best Practices for Working Effectively With Legacy Code?

Working with legacy code can keep even the best programmers awake at night. It often involves laborious debugging of individual methods and discovering illogical - though sometimes only at first glance - dependencies. From this article, you’ll learn how legacy code is created and what techniques and tools you should use to work with it effectively while increasing your productivity and avoiding unnecessary stress.

What is legacy code?

Legacy code is a term that refers to existing source code that was created in the past and remains in use. At the beginning of a project, it may have been understandable and readable. Over time, however, all the deviations from good programming practices and original assumptions made by the developer or team eventually became a big problem. As a result, such code can be difficult to understand, maintain and develop due to a lack of documentation or poor structure.

Developers have different opinions about legacy code - some may see it as a challenge, others as a burden. It’s important to find effective strategies for working with it to ensure that the development of an application or website continues. How can you recognize legacy code? 

Signals indicating that you’re dealing with a legacy code

There are several clear indicators that will allow you to judge that the code is legacy in nature. Here are examples of some of them, picked out by experienced developers at Droptica:

1. Code in a language other than English - using a unified programming language helps improve the code clarity, making it easier to understand and maintain by other developers in the future. Seeing a variable isPremiumUser, any developer will recognize the purpose of its use. On the other hand, using the Polish variable jestUzytkownikiemPremium can be confusing or incomprehensible to people who don’t know the Polish language.
    
2. Poorly formatted code - the code’s readability has a key impact on the efficiency of the work. By using non-standard formatting, the programmer makes the code readable only to him (at least until he forgets what it was supposed to be used for), and at the very first changes or debugging, such code will cause problems.
    
3. Non-object-oriented code - is often considered legacy code because object-oriented programming is now the dominant paradigm. Non-object code can be characterized by a lack of object-oriented structure, global variables, procedural complexity, and outdated design patterns, making it difficult to maintain and develop.
    
4. Code without testability - the lack of automated testing for code doesn’t allow for effective verification of its correctness and performance. As a result, it’s more error-prone, difficult to maintain and develop. Not testing the code can also lead to such changes, which carry the risk of unwanted side effects or regressions. For example, by fixing one element, a programmer may inadvertently break several others in the process and not even notice it. 
    
5. Code without documentation - is sometimes considered legacy code because of the difficulty it creates in understanding its operation, goals, and dependencies. No proper documentation makes it difficult for others to make changes, maintain and develop the code. It can also lead to the need for detective work, which increases the risk of errors and affects the developers’ efficiency.
    
6. Unsupported software - support for software (programming language, framework, modules, and additional libraries) includes regular updates, security patches, and technical support from developers. No active support means that the software may be outdated, contain security vulnerabilities, and not interoperate with new environments. With such software, code maintenance and development becomes more difficult.

How to eliminate legacy code from a project?

Eliminating legacy code while working on the project is critical to maintaining code quality and facilitating future software development. Several effective practices can be implemented right at the code-writing stage so that the code isn’t seen as a legacy in the future.

1. Writing code according to standards

Creating code according to standards is an important factor in preventing legacy code. Using uniform coding standards, such as naming, file structure, formatting, and comments, makes it easier for other programmers to understand the code. Thanks to that, the code becomes clearer, easier to maintain and modify, minimizing the risk of it being considered legacy code in the future.

In addition, using good practices, such as splitting into modules, properly managing dependencies, and avoiding excessive complexity, helps create more flexible and scalable code that is more likely to be developed over the long term.

2. Applying the principles of good programming

Important in reducing legacy code is good programming principles implementation. These include, for example, the SOLID and KISS approaches: 

• SOLID is a set of software design principles that promote the flexibility, scalability, and maintainability of code through the application of 5 rules. You can read more about this in the article: Code refactoring best practices that will help you in your daily work.
   
• KISS, or "Keep it simple, stupid," is a rule that can be simply explained by the slogan: prevent unnecessary complication of activities. If you can make something easier, just do it.

Using these principles and other proven design patterns helps keep code readable, modular, and easily extensible. In addition, keeping code clean by eliminating excessive complexity, redundancy, and unnecessary dependencies also reduces the risk of code becoming legacy code.

Practices such as regular code reviews, documenting, and using descriptive variable and function names also contribute to keeping code in good shape and minimizing the risk of legacy code.

3. Working with the tech lead to control the application development

Another best practice for working with legacy code is to involve a technical leader (tech lead) in the process. This specialist should control the development of the application and its architecture in order to avoid legacy code creation for several important reasons.

First, the tech lead is responsible for ensuring architectural consistency and conformance in the project. By overseeing the team's work, the tech lead can monitor whether good programming practices, design principles, and coding standards are being followed, helping to maintain code quality and avoid creating potential legacy code.

Second, controlling the application development allows the tech lead to keep track of any changes in requirements and technologies. As the application changes, the tech lead can adjust its architecture to meet new requirements and use the latest techniques and development tools. This prevents the application from becoming outdated and difficult to maintain.

Finally, the tech lead should manage technology debt. This specialist can identify areas that need code refactoring, patching, and optimization to keep the code in good shape. This prevents the creation of legacy code, leading to difficulties in implementing changes.

4. Creating code without comments

Writing code according to the principle "good code needs no commentary" helps avoid creating legacy code for a simple reason. When code is readable in itself, it means that it’s well-organized, has appropriate variable and function names, and is written simply and intuitively. It doesn't need additional descriptions because other programmers understand its intent and operation. 

The above rule of thumb allows developers to change their approach somewhat. It's worth taking an objective look at the code being written and considering whether someone else can decipher it at a glance without additional clues in the comments.

5. Using automatic tools 

Using tools that watch for adherence to good programming principles reduces legacy code. With code analysis tools and linters, you get feedback on programming compliance, which helps avoid mistakes and bad practices. 

Automated testing tools also detect errors and inconsistencies, which minimizes the risk of degrading code to legacy code status. As a result, using them helps create more quality and durable code.

If you’re taking over a project with legacy code. In that case, it’s a good idea to take the time, in the beginning, to analyze the code with one of the many tools available (its selection should be tailored to the language and type of project). They often automatically correct basic errors, such as lousy formatting or poorly chosen variable case.

Tools to make working with legacy code easier

Working with legacy code can be easier for you with several tools that will help you detect it, automatically correct the formatting, and suggest what function to use in place of its obsolete (deprecated) predecessor. These, of course, should be matched to the programming language and environment in use. Here you’ll find examples of tools designed for PHP development and JavaScript.

Tools for legacy code verification 

In addition to the aforementioned signals indicating that you’re working with legacy code, you can also take help from an IDE (Integrated Development Environment). Most programs will, to a greater or lesser extent (this may also depend on their settings, which you should familiarize yourself with), draw attention to duplicate code fragments, incorrect formatting, or deviations from the chosen coding standard. You can also often install extensions to them that focus on working with a specific framework, such as Drupal, Symfony, or Laravel.

When checking the project's software update, it’s worth remembering that a lot of information about the software versions in use is available in the website administration panel. There you can usually find a list of modules that need updating. On the frontend side, on the other hand, browser plugins such as Wappalyzer will come to your aid. They detect what technologies are used on the web page and analyze their performance.

A scan of the Droptica.com website made with the Wappalyzer (source)

Tools for organizing legacy code

You can correct many of the smaller errors associated with legacy code by using tools designed for specific languages and frameworks. After analyzing the code, they’ll present a list of detected errors, usually informing you that you can automatically fix some of them. Here are examples of such tools: 

• Code Sniffer - a popular tool among PHP and Drupal developers. After setting the appropriate coding standard, it offers in-depth code analysis.
   
• CS Fixer - a reliable solution for developers using the Symfony framework that automatically fixes and adjusts code formatting to established standards, improving the readability and consistency of the project.
   
• ESlint/JSlint - popular static JavaScript code analysis tools that help developers maintain clean and consistent code by identifying and reporting potential bugs and coding inconsistencies.

Source: eslint.org

• PHPStan - a powerful static code analysis tool for the PHP language that allows developers to detect errors, type incompatibilities, and potential problems at compile time, improving code quality and reliability.
   
• Larastan - an extension for PHPStan that provides static code analysis for applications based on the Laravel framework, enabling developers to detect errors and improve code quality at compile time.
   
• Rector - a tool for the PHP language that enables the automatic transformation of source code to conform to new standards, best practices, and conventions. It makes it easier to update a project to the latest PHP versions and improves code readability and quality.

Practices in preventing legacy code - summary

Legacy code is a term for existing code that remains in use. Many developers find it difficult to work with and hard to understand due to, for example, not adhering to the coding standards of a language or framework or using outdated technologies. 

Working with legacy code can be made easier by implementing the above-mentioned strategies and using tools designed to maintain clean code. They help with analysis and will automatically correct smaller errors. It's also a good idea to remember and try to implement unit tests to make sure that the changes you make have the intended effect. If you need additional support with legacy code, our experienced PHP, Symfony, or Drupal development team will help you find the best strategy.