Empirical comparison of graphical and annotation-based re-documentation approaches

Re-documentation is a complex activity that follows the comprehension of the code. Programmers record the knowledge they have gained in the form of text, views and diagrams that address specific aspects of the system under maintenance. Re-documentation of existing software can be achieved in several ways. The authors focus on two commonly used approaches: 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, design information is added in the form of code annotations. Diagrams may be produced, if needed, by an annotation-processing tool, which interprets the annotations previously inserted into the code and generates graphical views. The aim of this empirical work 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. Preliminary results with master students indicate the drawing editor approach as the most preferred and usable, with no penalty on the quality of the resulting diagrams and on the effort required.