A comparative study on the re-documentation of existing software: Code annotations vs. drawing editors

During software evolution, programmers spend a lot of time and effort in the comprehension of the internal code structure. Such an activity is often required because the available documentation is not aligned with the implementation, if not missing at all. In order to avoid wasting the time devoted to this activity, programmers can record the knowledge they have gained in the form of multiple, structural views that address the specific aspects of the system that they have considered. Re-documentation of existing software through design views can be achieved either using a drawing editor or annotating the source code. In the first case, diagrams are produced interactively, starting from the reverse engineered information. In the second case, diagrams are produced by an annotation processing tool. Most of current reverse engineering tools fall into the first case but they have serious limitations in the information they can recover automatically and they eventually require human intervention. The aim of the empirical work reported in this paper is the comparison of these two approaches, in order to understand which is easier to use and which the current limitations of both of them are.