10 refactoring best practices: When and how to refactor code

10 tips for when and how to refactor code

Teams should follow these code refactoring best practices to avoid costly mistakes or rework:

1. Fix software defects separately.
2. Avoid new features and functionality.
3. Refactor only when it's practical.
4. Understand the code.
5. Bring uniformity to coding practices.
6. Refactor, patch and update regularly.
7. Set clear objectives.
8. Focus on code deduplication.
9. Test early and often.
10. Use tools that help improve code.

These code refactoring tips are not necessarily sequential -- some will likely occur simultaneously. Software engineering teams might not need every tip here. Teams should assess where they need improvement and focus there.

Software defects often carry through the refactoring process. If a bug exists before code refactoring, it will likely remain afterward.

1. Fix software defects separately

Code refactoring is not troubleshooting or debugging.

The process cannot address software flaws by itself, only issues with application design or implementation. It is a way to remediate code smells, i.e., undesirable code attributes, such as excessively long routines or separate routines that are nearly identical.

Software defects often carry through the refactoring process. If a bug exists before code refactoring, it will likely remain afterward. Thus, the right time to perform refactoring is once the software's bug rate -- tracked via the number of help tickets, support requests or another measure -- is acceptably low. Refactoring should happen on a mature codebase.

Keeping bug fixes and refactoring separate helps developers identify the source of new issues. If developers refactor and debug code at the same time, it's virtually impossible to determine the cause-and-effect relationship in the new version of the software.

Some issues, however, require intervention. For example, if a module in the codebase throws unpredictable exception errors when it interrogates certain hardware devices -- despite repeated efforts to remedy the problem -- the team should refactor. In this example, developers already know the source of the problem, and refactoring might fundamentally rework the way in which the module queries those devices.

2. Avoid new features and functionality

Refactoring is a form of housekeeping developers perform to make code clearer, cleaner and more efficient. The process is not an opportunity to change functionality or add features. New features and functions are for after refactoring is complete.

A test-driven development (TDD) technique called red/green/refactor reflects how to refactor code:

1. Red. The engineering team sets a goal that the software does not currently meet.
2. Green. Developers add to or change the software to meet the goal or pass the test.
3. Refactor. Developers clean up the code before the cycle repeats.

Segregating refactoring and feature development, just like defect fixes and refactoring, can reduce unnecessary troubleshooting and limit risk. Refactored code should not change anything; the software should exhibit the same behaviors and pass the same tests. If behavior changes, code refactoring work is often the culprit. The engineering team must roll back to the previous version.

3. Refactor only when it's practical

Code refactoring requires software development resources.

Developers can't create new features and perform maintenance at the same time. Teams should evaluate the SDLC and roadmap to determine whether it's more efficient to refactor or create a new build from scratch.

Refactoring is a good choice when a modest developer investment yields more efficient, readable and maintainable code. Developers might refactor code when they want to reduce the number of processor or I/O cycles, for example.

They also might refactor to improve both compatibility and stability. Rather than make repeated calls to obtain the same state, for example, refactored code could make a single call, with a variable to retain the state once and then simply reuse that variable, as opposed to making repeated calls.

It's easy to lose control of the project's scope. These two code refactoring examples demonstrate value with limited investment:

1. Standardizing variable names and nested formats to make code more readable.
2. Modifying one routine to do the work of several similar routines, shrinking the software's memory footprint.

Teams should redesign and replace with new code, based on current standards and best practices, when the scope doesn't fit refactoring. Sometimes, code is too old or convoluted for developers to make sense of it. A change to the hardware platform might also require a rewrite if it goes beyond refactoring's scope.

4. Understand the code

Developers often define the goals of a refactoring project upfront. They should figure out what the code does and how it works before starting. Devs should do the following:

• Review the code to understand its processes, methods, objects and variables.
• Ensure junior developers and anyone unfamiliar with the product are comfortable with the codebase.
• Discuss and annotate the code carefully as a team. Highlight areas of interest -- sensitive routines, variables, objects or methods -- and then fill in any missing comments.

5. Bring uniformity to coding practices

Coding is usually a team sport, with each developer responsible for separate parts of the codebase. However, developers bring unique approaches and preferences to their tasks. As the code changes from individuals' input, the overall codebase becomes difficult for developers to read and understand. This confusion adds tremendous time and cost to troubleshooting and debugging.

To bring uniformity, developers should do the following:

• Create the most readable code possible when refactoring.
• Apply consistent coding techniques across the entire development team. For example, developers can add meaningful comments, indents, line spacing and other readability formatting to make software code easier to comprehend.
• Streamline the coding approach for the future, and remove irregularities to make code more maintainable.

6. Refactor, patch and update regularly

Regular update or patch cycles help development teams realize more value in their refactoring efforts. Modern software development cycles include regular patches and updates. With this cadence, developers naturally learn the codebase, as well as when and where to refactor code.

Code refactoring helps address technical debt, i.e., any shortcut or workaround in code that creates a short-term gain but long-term issues. As with financial debt, technical debt requires investment to reduce it. Refactoring generates the most ROI when it can address a significant issue but without much time and effort. Regular patch cycles help reduce this time and effort by reducing the developers' knowledge gap and keeping the software working.

Ideally, developers shouldn't refactor any code concurrent with patch or update cycles, but they can make refactoring requests iteratively. Project managers can then prioritize the requests and create a refactoring to-do list. The list informs how they allocate development resources to the most meaningful and effective refactoring tasks.

7. Set clear objectives

Refactoring is rarely a one-time, all-or-nothing effort. In practice, how an engineering team refactors code can take many forms, with varying levels of complexity. It's easy for a developer to stray from unclear objectives. Developers should do the following:

• Set a clear scope and goals early in the code refactoring initiative to avoid delays and extra work.
• Delineate what, how and when to refactor code by defining what refactoring actions will -- and won't -- include.
• Set small and specific goals that don't depend on other tasks.
• Establish timelines and delivery objectives that fit within existing workflows, such as CI/CD processes.

For example, a developer could refactor to simplify a vital subroutine and then stop. Later on, developers could break the structure of the large method into several small routines. In another example of goal-driven refactoring, developers could initiate a refactoring project to look for and eliminate hardware dependencies, such as directions to check for specific processors, to decouple the app from its infrastructure.

When setting the code refactoring scope, it helps to choose a development approach, such as TDD or behavior-driven development (BDD). With a set development approach, the team can refactor code with an eye toward testing and ensure that the application continues to operate as expected. The refactored code should pass TDD, BDD or other tests unique to the approach. If it fails any tests, an error or oversight might have occurred. Developers should then debug accordingly.

8. Focus on code deduplication

Once the team knows when to refactor code and what a typical project entails, they should train developers on the best candidates for refactoring. Duplicate functions that use two or more methods or routines to achieve similar results are prime refactoring candidates.

Duplicate or similar functions pose three distinct problems for code:

1. Duplications expand the software's footprint, wasting system resources.
2. Changes to one routine might also necessitate changes in others. Otherwise, logical or functional errors could threaten the software's stability or security.
3. Duplication adds complexity, which is a burden during testing, debugging and troubleshooting.

Developers can combine similar or duplicate functions into a single method to create better code.

9. Test early and often

While code refactoring doesn't change software functionality, it still requires test coverage. Testing checks that refactored code functions as intended and doesn't introduce any flaws.

Every time a developer completes a refactoring task, teams should test the code. Refactoring tasks with multiple steps or phases should undergo multiple rounds of testing. Teams should always maintain a rollback plan.

The established tests for the codebase should not change as a result of refactoring. If tests fail, that likely means someone introduced a bug. However, a test can also fail if the criteria no longer apply to the refactored code. For example, a code refactor might change object classes, such as some low-level objects subsumed into a higher class. In that situation, teams should rewrite the tests. Such issues usually don't affect BDD tests because the tests evaluate the software's outward behaviors.

10. Use tools that help improve code

Software development tools can help automate code refactoring tasks. These tools accelerate refactoring and catch common code issues that might otherwise go unnoticed.

Examples of tools include code editors, libraries and IDEs for a variety of programming languages, such as the following:

• Eclipse and IntelliJ IDEA for Java.
• Visual Studio for .NET and C++.
• Wing Python IDE, Pylint and PyCharm for Python.
• Scientist testing library for Ruby.
• SonarQube for detecting code smells in multiple languages.
• GitHub Copilot for AI-powered refactoring suggestions.

Editors and IDEs also help developers adhere to code maintainability standards, such as consistent code formats and variable name conventions. These details, while often overlooked, reduce refactoring in the future by enforcing rules upfront.

Stephen J. Bigelow, senior technology editor at TechTarget, has more than 30 years of technical writing experience in the PC and technology industry.