How to document external libraries that have been adopted into an existing codebase?

Question

I have been using an external library for a while now. Unfortunately, it stopped receiving updates, and has since been adopted into my codebase.

The issue is the library was poorly documented in the first place. It was picked out of necessity and because it was the only option. Now my question is, how should I document it and how should I go about adopting it into the codebase. The library works well, but the code standards are not up to par with the current codebase and the documentation leaves a lot to be desired.

More specifically:

• Is it worth refactoring the entire library, or extracting only the portions used?
  • Should it be considered SOUP going forward or fully adopted?
• Is it worth documenting everything, or only the portions that need to be used?

I recognize that these answers will vary on a case by case basis, but I am wondering about the general best practice in this scenario, or some questions to ask myself when making these decisions.

Answer 1

Because you do not know the development methodologies and practices used to build the software, it remains software of unknown provenance (SOUP). However, SOUP can usually be used in safety-critical systems if you have the appropriate controls in place to mitigate risk. In my experience, these controls often include things like performing malware scans, static analysis (including human code reviews), additional testing (if there's insufficient test coverage), and dynamic analysis that covers the SOUP.

If the external library is no longer maintained and you intent to incorporate it into your product, I don't see why you can't document what you have done to assert the safety and security of that code, do it once up-front, and then continue the risk mitigation controls if you update it. A lot of the risk mitigations that you would apply to SOUP (like static analysis, automated test coverage, and dynamic analysis) are things that you would also want to do to your own software source code that you develop in-house. Extracting the relevant portions would probably reduce the scope of the risk mitigations and reduce the cost of asserting that the software is correct.

The only concerns would be around if the licensing of the library allows for that kind of integration and the impact on your source code.

Answer 2

If it ain't broke, don't fix it

If you have a library, and it shows no bugs when called in the ways that you use it, then refactoring that library can only introduce new bugs that weren't there before.

Even if the original maintainer has abandoned it, that will introduce no new bugs. Only start worrying if someone discovers a nasty security flaw.

Document what you need

See if one of the auto-documentation tools will do what you need. If not, reverse engineer the documentation for the bits of the library that you use. Maybe semi-document the bits you don't, so that people know they are there.