What does my Source Code Do? – Documentation of Legacy Code

Time to Read 5 min

Are you still using old, undocumented source code in your embedded project? Have you lost the knowledge of parts of your code base? Do you need documentation of your existing source code for an upcoming safety certification?

Why Re-Document Old Source Code?

Does this sound familiar? The source code of your embedded software project was written many years ago. Cost and time pressures then and now meant that the source code was poorly documented.  Engineers who still know the structure and functionality of the source code are becoming increasingly rare. The original requirements are unclear and no longer known to all involved. Changes and maintenance become more and more expensive and risky. Urgently needed adjustments are delayed.

But this does not have to be the end. Your old source code is not worthless. It has its own qualities. Old source code is usually well tested (in the field) and confidence in its correctness and reliability is high. It is efficient because the available computing power was often very limited when it was written. In addition, re-implementation can also be risky because the result is usually less tested and because re-implementations are prone to e.g. feature creep and the 2nd system effect.

If you even plan to reuse your existing source code for a functional safety project, you are forced to document your source code and clarify the requirements anyway. Meanwhile, the same applies if information security is a concern for you.

What Belongs into the Software Documentation?

Source code can be re-documented, making it maintainable and fit for the future. For functional safety, the requirements for software documentation are specified quite clearly, but they are also very far-reaching. For example, in addition to writing documentation, you also have to perform a software safety analysis (software FMEA). For this, you need precise knowledge of the software architecture and software functionality.  But also for non-safety related projects some of the following documentation elements can be useful:

• Functional and non-functional requirements incl. traceability:
  • what behavior is guaranteed by the software?
• Structural design:
  • the static view of the software, class diagrams, dependencies, packages
• State diagrams, sequence diagrams:
  • the dynamic view of the software
• Control flow diagrams:
  • how decisions are made
• Data flow diagrams:
  • from where to where do the data elements flow
  • what information is needed where in the code?
• Data dictionary:
  • which data elements exist, and how are they represented.

In addition, depending on the project, there is documentation at a lower level of abstraction, e.g.:

• Comments in the source code
• Traceability in the source code:
  • why does the function exist?
• Data dictionary:
  • detailed function parameters

Not all documentation elements are absolutely necessary and important for all projects. Here, it is important to carefully weigh up where an investment in documentation is worthwhile.

Can Software Documentation be Automated?

Some of the documentation elements mentioned above can be created very well by (partially) automated processes (scripts, use of CLANG/ LLVM) based on the existing source code. This includes in particular the structural design of the software and potentially also the data dictionary.

The subsequent documenting of the dynamic behavior, e.g. the production of condition diagrams, can be partially automated, too. The condition is however, that the structure of the implementation is straightforward and consistent. Here, it is advantageous if the original implementation is based on a consistent framework and on coding guidelines. If this is not the case, only a time-consuming manual analysis of the entire source code will help.

Unfortunately, the control flow and the data flow in an aging embedded software project is often very opaque due to optimization measures and cannot be extracted by automated processes. Nevertheless, a manual analysis by an experienced embedded software engineer makes it possible to regain a good overview.

The same applies to documentation elements that require experience, creativity and an alignment of all stakeholders. For example, this includes the functional and non-functional requirements, as well as establishing traceability between requirements (down to the source code, if necessary). The knowledge needed to gather the past and current requirements is usually only available in the heads of the remaining engineers and product managers. This knowledge can be made available again, for example, with targeted interviews.

How do I come to a meaningful and useful software documentation?

The subsequent creation of software documentation is a time-consuming and expensive process. It is therefore worthwhile to plan exactly which documentation elements in which level of detail you need in order to achieve your goals efficiently.

The topic of testing and the creation of test lists has been left out of this blog. However, efficient testing always relies on a well-documented architecture and complete requirements.  It is as relevant a part of high-quality software development as is documentation.

We have extensive know-how in documentation and certification and can provide you with competent advice. If you have questions about subsequent documentation of existing software, safety certification or testing of embedded software, use our SolceptClinic. And best of all: this first time-boxed consultation of 30 minutes costs you nothing.

Daniel Megnet 

Do you have additional questions? Do you have a different opinion? If so, email me  or comment your thoughts below!