A qualitative assessment of the efficacy of UML diagrams as a form of graphical documentation in aiding program understanding

ABSTRACT

Graphical documentation is often characterized as an effective aid in program understanding. However, it is an open question exactly which types of graphical documentation are most suitable for which types of program understanding tasks (and in which specific usage contexts). The Unified Modeling Language (UML) is the de facto standard for modeling modern software applications. This paper describes an experiment to assess the qualitative efficacy of UML diagrams in aiding program understanding. The experiment had participants analyze a series of UML diagrams and answer a detailed questionnaire concerning a hypothetical software system. Results from the experiment suggest that the UML's efficacy in support of program understanding is limited by factors such as ill-defined syntax and semantics, spatial layout, and domain knowledge.

REFERENCES

• 1: Scott W. Ambler, The Elements of UML(TM) Style, Cambridge University Press, New York, NY, 2002
• 2: David Budgen , Gene Hoffnagle , Matthias Müller , François Robert , Asma Sellami , Scott Tilley, Empirical Software Engineering: A Roadmap Report from a Workshop held at STEP 2002, Montréal, October 2002, Proceedings of the 10th International Workshop on Software Technology and Engineering Practice, p.180, October 06-08, 2002
• 3: Elliot J. Chikofsky , James H. Cross II, Reverse Engineering and Design Recovery: A Taxonomy, IEEE Software, v.7 n.1, p.13-17, January 1990 [doi>10.1109/52.43044 ]
• 4: Shihong Huang , Scott Tilley, Workshop on Graphical Documentation for Programmers: Assessing the Efficacy of UML Diagrams for Program Understanding, Proceedings of the 11th IEEE International Workshop on Program Comprehension, p.281, May 10-11, 2003
• 5: IBM Corp. "UML Resource Center". Online at http://www.rational.com/uml.
• 6: IBM Corporation. "The Rational Unified Process (RUP)." Online at http://www.rational.com/products/rup/index.jsp.
• 7: Claire Knight , Malcolm Munro, Comprehension with[in] Virtual Environment Visualisations, Proceedings of the 7th International Workshop on Program Comprehension, p.4, May 05-07, 1999
• 8: Henk Koning , Claire Dormann , Hans van Vliet, Practical guidelines for the readability of IT-architecture diagrams, Proceedings of the 20th annual international conference on Computer documentation, p.90-99, October 20-23, 2002, Toronto, Ontario, Canada [doi>10.1145/584955.584969]
• 9: Philippe Kruchten, The 4+1 View Model of Architecture, IEEE Software, v.12 n.6, p.42-50, November 1995 [doi>10.1109/52.469759 ]
• 10: Nenad Medvidovic , David S. Rosenblum , David F. Redmiles , Jason E. Robbins, Modeling software architectures in the Unified Modeling Language, ACM Transactions on Software Engineering and Methodology (TOSEM), v.11 n.1, p.2-57, January 2002 [doi>10.1145/504087.504088]
• 11: H. A. Müller , S. R. Tilley , M. A. Orgun , B. D. Corrie , N. H. Madhavji, A reverse engineering environment based on spatial and visual software interconnection models, Proceedings of the fifth ACM SIGSOFT symposium on Software development environments, p.88-98, December 09-11, 1992, Tyson's Corner, Virginia, United States
• 12: Object Management Group (OMG). "UML 2.0 Standard Officially Adopted at OMG Technical Meeting in Paris." June 12, 2003. Online at http://www.omg.org/news/releases/pr2003/6-12-032.htm.
• 13: Object Management Group. Online at http://www.omg.org.
• 14: Robert Pierce , Scott Tilley, Automatically connecting documentation to code with rose, Proceedings of the 20th annual international conference on Computer documentation, p.157-163, October 20-23, 2002, Toronto, Ontario, Canada [doi>10.1145/584955.584979]
• 15: Helen C. Purchase , Linda Colpoys , Matthew McGill , David Carrington, UML Collaboration Diagram Syntax: An Empirical Study of Comprehension, Proceedings of the 1st International Workshop on Visualizing Software for Understanding and Analysis, p.13, June 26-26, 2002
• 16: Rational Software Corp. "PearlCircle." Online at http://rdatux.rational.com/auction/index.jsp.
• 17: Scott R. Tilley, The canonical activities of reverse engineering, Annals of Software Engineering, v.9 n.1-4, p.249-271, 2000
• 18: Tilley, S. and Huang, S. "Assessing the Efficacy of Software Architecture Visualization Techniques for Recovered Artifacts." Dagstuhl Seminar 03061: Software Architecture Recovery and Modeling (Feb. 2 - 7, 2003; Schloss Dagstuhl, Germany).
• 19: Scott Tilley , Shihong Huang, Documenting software systems with views III: towards a task-oriented classification of program visualization techniques, Proceedings of the 20th annual international conference on Computer documentation, p.226-233, October 20-23, 2002, Toronto, Ontario, Canada [doi>10.1145/584955.584988]
• 20: Scott Tilley , Shihong Huang, On Selecting Software Visualization Tools for Program Understanding in an Industrial Context, Proceedings of the 10th International Workshop on Program Comprehension, p.285, June 27-29, 2002
• 21: Tilley, S. and Huang, S. "On the Emergence of the Renaissance Software Engineer." Proceedings of the 1st International Workshop on Web Site Evolution (WSE'99). Atlanta, GA: October 5, 1999.
• 22: Scott Tilley , Ken Wong, Workshop on graphical documentation for programmers, Proceedings of the 20th annual international conference on Computer documentation, p.234-235, October 20-23, 2002, Toronto, Ontario, Canada [doi>10.1145/584955.584989]
• 23: Bill Thomas , Scott Tilley, Documentation for software engineers: what is needed to aid system understanding?, Proceedings of the 19th annual international conference on Computer documentation, October 21-24, 2001, Sante Fe, New Mexico, USA [doi>10.1145/501516.501570]

INDEX TERMS

Primary Classification:
  D. Software
  D.2 SOFTWARE ENGINEERING
      D.2.7 Distribution, Maintenance, and Enhancement
          Subjects: Documentation

Additional Classification:
  D. Software
  D.2 SOFTWARE ENGINEERING
      D.2.2 Design Tools and Techniques

General Terms:
Documentation, Experimentation, Human Factors

Keywords:
Unified Modeling Language (UML), assessment, graphical documentation, program understanding