I’ve previously mentioned that one of the traits of legacy code is that it lacks documentation or the existing documentation is of inferior quality. Let me now provide some guidance on how to document a legacy code project, or any project for that matter.
Start With the Overview
The minimum amount of documentation a piece of software has must be a description of what the software does. What problem is it trying to solve?
A next step would be a high overview of how this problem is solved. Don’t document the nitty-gritty details yet. Just a description of your approach is fine.
Next, a global picture of the different links to the system. Where are you getting your inputs? Where are you sending your output? Are you using external services? If so, which?
This should be a good start. It makes little sense to document each and every code file in your application, if you can’t get an overview of your application at the click of a button.
Drill Down
After getting the overview right, you can start drilling down into more detail.
A first step is to make a diagram of the different components of your application and the relationships between them. Also, for each component, document the responsibilities of this component.
The definition of a component may differ based on the type of your application. Best to consult your team on this. But don’t go down to the single code-piece level just yet. Only document the different building blocks of your legacy application.
This will already provide great insights for your team. Especially when they need to add new features to the legacy software. The overview of responsibilities will give them the chance to add the new feature to the correct components.
This documentation will also show you where pieces of legacy code issues are. Maybe some components aren’t used anymore. Or maybe the relationships between them are more of a tangled mess than anyone had thought.
But Not Too Much
After having documented all the components of your application, you might want to stop for now. Drilling down too far and documenting too many details is a sure way of creating “legacy documentation.” This is where parts of your documentation are no longer valid, i.e. they are out of sync with the code.
Once you have very detailed documentation, it becomes a heavy task to update it along with the changing code. And it’s only a matter of time before updates to the documentation are forgotten or mistakes are made. After a while, it might not be clear if the code is wrong (i.e. it contains a bug) or the documentation is just not up-to-date. This leads to questions, puzzled developers, inefficient discussions and just plain wasted time and money.
However, it is OK to document specific details that are important. For example, in the automation of an industrial machine, you may want to provide a diagram about the normal work flow of the machine. In an order processing application, you can document the different phases an order goes through and how the application behaves.
Document Special Cases
The details that you can and should document, are special cases. Especially in legacy code, there are many quirks and exceptions to the normal flow. These have all been introduced with a good reason. Rediscovering this reason isn’t always easy, and sometimes impossible. But at the very least, you should document the fact that these cases exist in the first place.
Other Things To Document
There are many other things that you can document, depending on how useful they are for your team:
- non-functional requirements (things like platform compatibility, performance, deployment procedures, etc)
- contracts with external interfaces
- coding standards
- a glossary of domain-specific terms
Automate
This all seems like a lot of work. And it often is. But nobody is telling you to do it all at once. You can ask your team to document as they discover things that need to be documented.
But one thing you should ask them to do is to automate as much as possible. Generating a website from the different pieces of documentation isn’t very hard with modern tools. There is also software that will generate diagrams of your application’s components for you. Coding standards can be enforced automatically. You can write functional requirements (use cases) that can automatically be run as tests.
There’s much to be automated, leaving your team more time to focus on working on the legacy software. Contact me if you’re having doubts about what you can automate in your project.
Maintain the Documentation
One last, but important note: you and your team will have to maintain the documentation. Automate as much as you want, there will still be some manual work involved.
Software development is more than cranking out code. Documentation is part of it too. A mature and responsible developer will take time to keep documentation up-to-date because it will save time and effort in the future. Especially in legacy code projects.
The post Documenting Legacy Code appeared first on Red Star IT - Helping Managers Tackle Legacy Code.
Top comments (0)