Home » Software Development » Code Refactoring vs Architecture Refactoring

About Marco Di Stefano

Marco is a software engineer specialized in software architecture and process automation. He has been involved in all the software v-cycle phases and actually he works for the railway industry.

Code Refactoring vs Architecture Refactoring


Everybody knows the meaning of Refactoring; the base of Agile Programming, and the best way to continuously increase the code quality. But Refactoring is not always the same, two different categories can be defined:

  • Code refactoring
  • Architecture refactoring

Code refactoring vs Architecture Refactoring

The term Architecture Refactoring started to be used in the last years, bringing some confusion about its meaning and its difference with code refactoring. Someone could say that there is no difference, cause when refactoring the architecture is always a refactoring done at the level of the code. So let’s try to define the two types and focus on the differences:

  • Code Refactoring aims modifying the code without changing its behavior with the main scope of increase the overall software quality. One refactoring is usually a small task, but several refactorings applied to the code can considerably increase its quality. Several books have been written about code smells and refactoring patterns. Finally it exists automatic tools able to detect code smells (FindBugs, PMD, CheckStyle) and even do automatic refactoring (NetBeans IDE).
  • Architecture Refactoring aims changing the software architecture, reorganizing the existing code into new logical layers with the main scope of increase the overall software quality and surpass architecture/infrastructure limitations that critically mine systematic qualities as (for example) scalability, extensibility, evolvability, testability and robustness of the actual solution system. A major challenge of this kind of refactoring is trying to reuse as much as possible existing code, to avoid writing a new software. Use of automatic tools can be few help (maybe just to detect circular dependencies), here the most work will come from your brain and experience.

So, what is the difference? When refactoring code, we change the way the code is written, once when refactoring architecture we change the way the code is organized in logical layers and components.

To better describe the differences I would like to focus on the following aspects:

  • Project management
  • Development management
  • Documentation
  • Implementation Environment

Project Management

By the point of view of project management the difference is big. Code Refactoring is usually agreed within the boundary of the development team since the associated risk is low and the impacts can be easily controlled and validated.

Clearly it is not the same for Architecture Refactoring! An agreement from management is necessary to be able to start the task as the associated risks and cost of the task can be elevate. Follows a list of what to do and what not to do when speaking with your manager:

  • Do an high level planning before any discussion, you must have an idea of the work
  • List the attainable improvements against the actual limitation
  • Try to identify the ROI with quantifiable metrics (depending on the project but money is the most common)
  • If refactoring is too big, propose a migration planning
  • Create a small team, when revisiting the architecture is not easy to make more than 2 people working at the same time (at least at the beginning)
  • Never say that the actual version is not good!

Development Management

Code Refactoring is a task that can be done by any developer as many tools exist to assist its execution. But Architecture Refactoring needs a bit more of expertise, as developers need to speak a bit of Software Architecture to be able to understand the changes, and Software Architects need a matured experience and (in most of the cases) a lot of courage!

The Software Architect has the duty to organize all the necessary meetings with the team involved in the refactoring to share with them the philosophy and objectives of the refactoring. Differently from Code Refactoring, it is better to have a full vision of the final design before to start to work.

Finally be sure to preserve the actual source code, and in operational environment a plan B can be put in place, to grant normal deliveries of the tools in case the refactoring tasks will present unexpected difficulties that can delay the original planning. A plan B can be for example a small development team, working in parallel with the refactoring team, that will include in the actual system the most urgent new requirements targeted in the refactored architecture. This should be part of the migration planning defined with your management.


Code Refactoring does not impact system documentation as Architecture Refactoring does. On top of all there are documents to be written as:

  • Migration planning
  • Motivation of the refactoring
  • Impact and cost estimations

And a list of existing documents will have to be modified as:

  • System design document
  • Enterprise Architecture document

Implementation Environment

Architecture Refactoring can have a huge impact on the implementation environment; for example it can be necessary to change the used IDE or build system, the continuous integration server, the test automation framework. It is better to analyze those impacts before to start the refactoring, to have a realistic idea of the cost of the task because an unexpected change in the implementation environment can arise great issues being discovered only in the final phase.


In my experience I had to face with several big Architecture Refactoring. Taking in consideration all the 4 described aspects helped me to finalize with success those tasks and to gain confidence with my management team. Finally, if you are a software architect I would like to mention another aspect, that is about personal feelings: Architecture Refactoring is not a proof of your mistakes or bad decisions, simply at a certain moment it becomes necessary and it can be the best way to challenge and confirm your skills!

Reference: Code Refactoring vs Architecture Refactoring from our JCG partner Marco Di Stefano at the Refactoring Ideas blog.

Do you want to know how to develop your skillset to become a Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you our best selling eBooks for FREE!


1. JPA Mini Book

2. JVM Troubleshooting Guide

3. JUnit Tutorial for Unit Testing

4. Java Annotations Tutorial

5. Java Interview Questions

6. Spring Interview Questions

7. Android UI Design


and many more ....


Receive Java & Developer job alerts in your Area

I have read and agree to the terms & conditions


Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Inline Feedbacks
View all comments