The importance of computer program maintenance can not be overstated. As the life-span of programs increases, and portions of those same programs are reused more frequently and are therefore more pervasive, many organizations may depend on legacy products, rather than new “from scratch” products, to achieve the bulk of their profits. The importance of maintenance, then, translates to huge costs by these companies to update, fix, streamline and generally maintain those products.

Trade and industry literature has estimated that anywhere from 60 to 75, and even as high as 90% of an organization’s budget is spent on maintaining their own software (1; 2; 3). Labor, specifically the amount of time spent by maintenance programmers understanding another person’s code, obviously accounts for a large portion of the cost. At least half of a maintenance programmer’s time is spent on this activity according to some studies (4; 5).

A software system’s documentation can do much to moderate the cost of that system’s maintenance. If the system’s documentation is up to date, correct and comprehensive, maintenance programmers will more easily be able to understand the operations and structure of that system (6). Comprehensive documentation is especially important when a programmer is introduced to a software system. In such a case the documentation provides insight about the system and helps the unfamiliar programmer quickly become familiar with complicated elements. Especially in the case of internal documentation, programmers new to an unfamiliar system may be able to utilize included information that allows them to forgo having to read the code itself and more easily attain a comprehensive understanding of the program (7; 8).

Elements of internal documentation—that is, imbedded source-code comments—were long ago thought to contribute to the understanding of a new program by someone unfamiliar with that program (9; 10; 11). Literature suggests that source-code comments help programmers learn and understand unfamiliar programs in a number ways. Programmers, for example, turn to comments to confirm or expand on a hypothesis formed while reading the associated code (9; 10), or look to comments to help them find pieces of code associated with specific portions but located elsewhere (12).

Studies since those published in the late 70’s and early 80’s have confirmed that imbedded comments do help people—those who have no or little knowledge about a particular program—comprehend that program (12; 13; 14; 15; 16). These studies have improved the perception of commenting source code as an important practice, made evident by the fact that in a recent study well over half of the organizations surveyed by the authors either had internal documentation guidelines or had partial internal documentation guidelines (6). The suggestion, then, is that industry recognizes the importance of source code comments and encourages their use.

Regardless of the results of studies suggesting how important comment are, literature from within industry implies that the comments are still not utilized enough or are not utilized in ways that help unfamiliar programmers understand a program (17; 18; 19; 20; 21). Programmers, it seems, do not often comment in such a way as to efficiently and effectively help readers of their code. The reason why has yet to be determined. 

1. Huff, S. (1990). “Information systems maintenance”. The Business Quarterly 55, 30-32.
2. Erlikh, L. (2000). “Leveraging legacy system dollars for E-business”. (IEEE) IT Pro, May/June 2000, 17-23.
3. Eastwood, A. (1993). “Firm fires shots at legacy systems”. Computing Canada 19 (2), p. 17.
4. Fjeldstad, R. & Hamlen, W. (1983). “Application program maintenance-report to to our respondents”. Tutorial on Software Maintenance, 13-27. Parikh, G. & Zvegintzov, N. (Eds.). IEEE Computer Soc. Press.
5. Standish, T. (1984). “An essay on software reuse”. IEEE Transactions on Software Engineering SE-10 (5), 494-497.
6. Kajko-Mattsson, M. (2005). A survey of documentation practice within corrective maintenance. Empirical software engineering, 10, 31-55.
7. Hunt, A. & Thomas, D. (2002). Software archeology. IEEE software, 19, 20-22.
8. Sim, S. E., & Holt, R. C. (1998). The ramp-up problem in software projects: a case study of how software immigrants naturalize. Proceedings of the 1998 (20th) international conference on software engineering, 361-370.
9. Brooks, R. (1981). A theoretical analysis of the role of documentation in the comprehension of computer programs. Proceedings of the 1982 conference on Human factors in computing, 125-129.
10. Brooks, R. (1982). Towards a theory of the comprehension of computer programs. International journal of man-machine studies, 18, 543-554.
11. Shneiderman, B. & Mayer, R. (1979). Syntactic/semantic interactions in programmer behavior: A model and experimental results. International journal of computer and information sciences, 8, 219-238.
12. Soloway, E., Pinto, J., Letovsky, S., Littman, D., & Lampert, R. (1988). Designing documentation to compensate for delocalized plans. Communications of the ACM, 31, 1259-1267.
13. Norcio, A. F., (1982). Indentation, documentation and programmer comprehension. Proceedings of the 1982 conference on human factors in computing systems, 118-120.
14. Prechelt, L., Unger-Lamprecht, B., Philippsen, M., & Tichy, W. F. (2002). Two controlled experiments assessing the usefulness of design pattern documentation in program maintenance. IEEE transactions on software engineering, 28, 595-606.
15. Nurvitadhi, E., Leung, W. W., & Cook, C. (2003). Do class comments aid java program understanding? Proceedings of the 33rd ASEE/IEEE Frontiers in Education Conference, 13-17.
16. Tenny, T. (1988). Program readability: Procedures versus comment
17. Campbell, N. (1996, October). Thirteen steps to better documentation. Computing Canada, 22, 28.s. IEEE transactions on software engineering, 9, 1271-1279.
18. Raskin, J. (2005). Comments are more important than code. ACM queue, 2. Retrieved online, June 2005 from:
    http://www.acmqueue.com/modules.php?name=Content&pa=showpage&pid=290
19. Ray, G. (1989, January). Disgruntled programmers needn’t have the last word. PC Week, 6, 45.
20. Thomas, R. A. (1984, May). Using comments to aid program maintenance. Byte, 416-422.
21. Zokaites, D. M. (2002, January). Writing understandable code; sure, you know that you should comment your code, but how well are you actually doing it? Here’s one developer’s perspective on documenting your application’s raison d’etre through comments, naming conventions and clean constructs. Software development, 10, 48-50.

Last update: 27-03-2009 13:41