Archive for May, 2017

Working with legacy code

Thursday, May 11th, 2017

Dealing with legacy code is usually inevitable for a Software Architect. In one way or the other, complex systems are built by cobbling together several lesser or equally complex systems. Successful organisations usually have a portfolio consisting of some legacy code which forms the basis of newer modules and applications which are being actively developed and maintained.

Unfortunately, system architecture rarely evolve in a way whereby the architecture is continuously refined and kept in pace along with the addition of new features and functionalities, making legacy code often poorly structured and poorly documented. In practice, market pressures, evolving business landscape and conflicting priorities between business stakeholders and technical stakeholders will conspire to make a code-base less and less maintainable over the years.

If the organisation and its management are progressive enough, they would have already understood the need to modernize the system and adopt state-of-the art technologies and architecture practices. But nevertheless, it is rarely a straightforward exercise and usually any transition of legacy systems can take several years.

But for any transition from a given architecture (say, a JEE based monolith) to a target architecture (say, microservices) to be successful, people who are involved in the transition efforts must have a decent understanding of the intricacies of the legacy system. Also it is worth noting that more often than not, legacy systems may not have a well defined architecture at all.

Following are some of the important lessons from my experience:

Respect the system

First thing is to understand that system has worked well enough and long enough for it to become your problem, so there must be something good about it. Also despite all the shortcomings, it has managed to mint money for the owners of the company and pay its bills, including your own salary.

Keep the doors of dialogue open to the original developers

It is likely that original developers have all left the company, leaving present developers all alone to deal with an ill documented system. Nevertheless, they may have been working under great pressures when they wrote the system. While you must appreciate the shortcomings of the system which they had build, you must also keep a door open for dialogue with them if they are available as consultants or freelancers

Deal with the sh*t

This may take weeks to months, depending upon the complexity of the system. Do not get easily carried away by the presentations given in the microservice conferences — they make everything sound very simple, simpler than they are in real businesses. Also I doubt whether some of those speakers who are full time speakers have that much time left to architect or develop complex solutions. Please note the key points which could smoothen the process of understanding a large, complex, monolithic, legacy code base

  •  Understand the business requirements — each class with more than 1000 lines has probably a history behind it
  • Read existing document — often you will be disappointed to know that there is not much documentation or Javadoc available, but do not give up. Also it is worth trying to understand the evolution of the code through user stories and bug reports by scanning a project management tool such as Jira
  • Check out the code, build it, run it locally even if you think you are too important to do that
  • Determine the edges of the system. Behind the curtains, almost all of the systems work by taking some inputs, process them and present or store the output. Follow the flow of data
  • Understand the data model — for very large systems, data-structure is usually relatively simpler than the code itself. Also there is higher chance that data model is better taken care by a DBA and could be cleaner
  • Identify and understand seams in the system — no explanations required
  • Approach it as an end-user — how does his actions get handled? Take one or two of the most critical use cases
  • Sketch and document — no need of doing it using UML, the key here is to keep it simple and understandable


An Architect or a developer who works with complex code-bases will sooner or later have to deal with legacy code. The key to tame such a system is patience and perseverance along with some of the practical tips which I have mentioned above