Comparison of different documentation styles for frameworks of object-oriented code

Abstract

Frameworks are increasingly employed as a useful way to enable object-oriented reuse. However, understanding frameworks is not easy due to their size and complexity. Previous work concentrated on different ways to document frameworks, but it was unclear which ones were actually better. This paper presents a novel way of investigating the different philosophies for framework documentation. The philosophies include minimalist, patterns-style and extended javadoc (Jdoc) documentation. Using a survey of 140 novices engaged in Swing intensive coding work, this empirical study discovered some guidelines for effective framework documentation for the Swing framework. The results suggest that different documentation is better for different goals.

Keywords:

• documentation
• empirical
• minimalist
• object-oriented frameworks
• patterns

AMS Subject Classification:

• 82-05
• 62D05
• 62K99

Acknowledgements

The study described in this paper would not be possible without the cooperation and willingness of the experimental subjects and course tutors. This research was supported in part by an award from the Intensification of Research and Development in Priority Areas (IRPA) grant, 04-99-01-00010-EAR.