Complementing Software Documentation

Abstract

To developers software often appears as a large number of modules each containing hundreds of lines of code. It is, in general, not obvious which parts of the source code implement a given concern. Typically, existing documentation is outdated (if it exists at all), the system’s original architects are no longer available, or their view is outdated due to changes made by others. However, even out-of-date documentation has value, particularly if the high-level abstraction has remained valid. If it is complemented with an up-to-date, more detailed overview of the concerns in the source code, the two information sources, documentation and code, together can be used for everyday maintenance tasks. A technique which has been proposed to provide such a complementary view is Latent Semantic Indexing (LSI). LSI arose from the problem of how to find relevant documents from search words and assumes there is some underlying or latent structure in word usage across documents. In our case, LSI is used to identify architectural concerns which reveal the intention of the source code based on the words occurring in that source code. However, the multitude of levers and knobs in the various steps of the approach makes it hard to use LSI as an off-the-shelf tool. In this chapter we describe the steps of the approach together with appropriate settings. These settings proved to be successful when applying the approach on the source code of Philips Healthcare. Using the optimal settings for our case we have conducted two case studies at Philips Healthcare where we used the approach to complement the existing toolset for managing the system’s documentation in order to improve the documentation and communication on the software. Using our approach, we were able to identify multiple concerns which were not yet documented.