Embedding constructural documentation in unit tests
Mathieu Nassif · eScholarship@McGill (McGill) · 2019
Software projects capture information in artifacts that include production code, test suites, and documentation. Because different artifacts serve different purposes, the information they encode can be redundant. We present an approach to mitigate this redundancy by allowing developers to encode in unit tests information that is used to automatically generate documentation fragments. The result is a set of documentation fragments injected in the reference documentation of the methods under test. We implemented this approach in the form of an Eclipse plug-in. The ability to regenerate the documentation fragments allows documentation to be automatically updated when unit tests are modified. This approach is part of the larger idea of embedding information in source code through the use of meaningful constructs, a concept we termed constructural documentation. We report on a multi-case study that provides insights on the pertinence of constructural information in real world systems. This study highlighted several practices that favor or prevent embedding constructural information in tests, such as the use of standardized local variable names to encode recurring concerns of a test, thus acting as anchors for constructural documentation. Combined with the detailed description of a working tool, the study shows constructural documentation to be a promising way to increase automation in software documentation practices.