Why is it important to retain documentation of legacy elements of a software system?

Legacy software is software which was coded a considerable time ago, but is still being used. It is important, indeed vital, to retain documentation of legacy elements of a software system for the following reasons-

  • Human memory is fallible. The original coders change, teams change, and even projects handled by the original coder change. It is impossible to recall why a particular module was written in a certain way, or why it was written at all.
  • Fixing bugs – Legacy software is notorious for the strange bugs they throw – and in order to fix them it is necessary for the current developers to know where in the code to plunge.
  • Not breaking it – Touching legacy software to fix bugs should be done with caution. One wrong line of code can break a “perfectly working” system, especially one that was “working” for so many years and is important enough to keep around
  • Upgrades – In order to upgrade systems – documentation of the original is essential
  • Inheritance of code – The developer who has newly acquired the legacy modules for maintenance has to quickly, and yet thoroughly, be brought up to date on its design and implementation. This is possible only through documentation.
  • Adding new features – Documentation of the existing system is needed to know how new features (that are to be added) can seamlessly be integrated
  • Revisions and Rollback– Legacy modules undergo various revisions over time – for new features or for bug fixes. It is necessary to have a documented history of revisions – in the case of ever needing to roll back to an earlier working version, or branching out code.
  • Re-writing – If a business decision is ever taken to re-write the legacy code with an up-to-date language (for instance from VB to VB.NET or VC++ to C#) then the documentation will help in providing a high-level abstraction of the necessary function, and prevent old coding mistakes from creeping into the new code.