Documenting software systems with views

ABSTRACT

Software professionals rely on internal documentation as an aid in understanding programs. Unfortunately, the documentation for most programs is usually out-of-date and cannot be trusted. Without it, the only reliable and objective information is the source code itself. Personnel must spend an inordinate amount of time exploring the system by looking at low-level source code to gain an understanding of its functionality. One way of producing accurate documentation for an existing software system is through reverse engineering. This paper outlines a reverse engineering methodology for building subsystem structures out of software building blocks, and describes how documenting a software system with views created by this process can produce numerous benefits. It addresses primarily the needs of the software engineer and technical manager as document users.

REFERENCES

• 1: Gixish Parikh and Nicholas Zvegintzov, editors. Tutorial on Software Maintenance. IEEE Computer Society Press, 1983.
• 2: P. Freeman, Tutorial, software reusability, IEEE Computer Society Press, Los Alamitos, CA, 1987
• 3: Will Tracz, Software reuse: emerging technology, IEEE Computer Society Press, Los Alamitos, CA, 1988
• 4: David H. Longstreet, Software Maintenance and Computers, IEEE Computer Society Press, Los Alamitos, CA, 1990
• 5: Nigel T. Fletton and Malcolm Munro. Redocumenting software systems using hypertext technology. In Proceedings of the iEEE 1988 Conference on Software Maintenance, pages 54-59, October 1988.
• 6: Nicholas Zvegintzov. Nanotrends. Datamation, p~ges 106-116, August 1983.
• 7: H.A. Mfiller, B.D. Corrie, and S.R. Tilley. Spatial and visual representations of software structures: A model for reverse engineering. Technical Report TR-74.086, IBM Canada Ltd., April 1992.
• 8: Hausi A. Miiller. Rigi - A Model for Software System Construction, Integration, and Evolution based on Module Interface Specifications. PhD thesis, Rice University, August 1986.
• 9: H.A. Mfiller and J.S. Uld. Composing subsystem structures using (k,2)-partite graphs. In Proceedings of the Conference on Software Maintenance I990, (San Diego, California, November 26-29, 1990), pages 12- 19, November 1990.
• 10: Jane E. ttuffman and Clifford G. Burgess. Partially automated in-line documentation (PAID): Design and implementation of a software maintenance tool. In Proceedings of the {EEE Conference on Software Maintenance 1988, p~ges 60-65, October 1988.
• 11: Johannes Sametinger. A tool for the maintenance of C-k+ programs. In Proceedings of the IEEE 1990 Conference on Software Maintenance, pages 54-59, November 1990.
• 12: L.D. Landis, P.M. Hyland, A.L. Gilbert, and A.J. Fine. Documentation in a software maintenance environment. In Proceedings of the IEEE Conference on Software Maintenance 1988, pages 66-73, October 1988.
• 13: Frederick P. Brooks, Jr., No silver bullet: essence and accidents of software engineering, Computer, v.20 n.4, p.10-19, April 1987 [doi>10.1109/MC.1987.1663532]
• 14: Frederick P. Brooks, Jr., The mythical man-month (anniversary ed.), Addison-Wesley Longman Publishing Co., Inc., Boston, MA, 1995
• 15: P. J. Brown, Interactive documentation, Software—Practice & Experience, v.16 n.3, p.292-299, March 1986
• 16: Duane Ressler , Dee Stribling, Designing and prototyping a portable hypertext application, Proceedings of the 8th annual international conference on Systems documentation, p.87-94, October 31-November 02, 1990, Little Rock, Arkansas, United States
• 17: S.M. Kosslyn. Image and Mind. Harvard University Press, 1980.
• 18: H. A. Müller , K. Klashinsky, Rigi-A system for programming-in-the-large, Proceedings of the 10th international conference on Software engineering, p.80-86, April 11-15, 1988, Singapore
• 19: M.E. Lesk. Tbl- A program to format tables. Technical report, AT&T Bell Laboratories, October 1986.
• 20: Vicki Coleman, Hardcopy to hypertext: putting a technical manual online, Proceedings of the 9th annual international conference on Systems documentation, p.67-72, October 1991, Chicago, Illinois, United States [doi>10.1145/122778.122789]
• 21: Frank A. Cioch. An audiovisual document for software maintenance. In Proceedings of the IEEE 1988 Conference on Software Maintenance~ pages 390-394, October 1988.
• 22: Scott Tilley , Hausi Müller, INFO: a simple document annotation facility, Proceedings of the 9th annual international conference on Systems documentation, p.30-36, October 1991, Chicago, Illinois, United States [doi>10.1145/122778.122784]
• 23: H.A. Mfiner. Verifying software quality criteria using an interactive graph editor. In Proceedings of the Eighth Annual Pacific Northwest Software Quality Conference, (Portland, Oregon, October ~9-31), pages 228-241, October 1990.
• 24: H.A. Mfller, J.R. MShr, and J.G. McDaniel. Applying software re-engineering techniques to health information systems. In Proceedings of the iMIA Working Conference on Software Engineering in Medical Informatics (SEMI), (Amsterdam, October 8-10, 199.0), October 1990.

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

General Terms:
Design, Documentation, Theory

Keywords:
reverse engineering, software documentation, software maintenance