Kari Laitinen
Abstract
Software developers and maintainers need to read and understand source programs and other kinds of software documents in their work. Understandability of software documents is thus important. This paper introduces a method for estimating the understandability of software documents. The method is based on a language theory according to which every software document is considered to contain a language of its own, which is a set of symbols. The understandability of documents written according to different documentation practices can be compared using the rules of the language theory. The method and the language theory are presented by using source programs with different naming styles as example documents. The method can, at least theoretically, be applied to any kind of document. It can also be used to explain the benefits of some well-known software design methods.
- Bennett, K., Cornelius, B., Munro, M., and Robson, D. Software Maintenance. In: McDermid, J. A. (ed.) Software Engineer's Reference Book, Butterworth-Heinemann, Oxford, England, 1991, chapter 20, 18 pages.Google Scholar
- Carter, B. On Choosing Identifiers. ACM SIGPLAN Notices, Vol. 17, No. 5. May 1982. pp. 54-59. Google ScholarDigital Library
- Coad, P. and Yourdon. E. Object Oriented Analysis. Prentice-Hall, Englewood Cliffs. New Jersey, 1990. 223 pages. Google ScholarDigital Library
- Curtis, B., Krasner. H., and Iscoe. N. A Field Study of Software Design Process for Large Systems. Communications of the ACM. Vol. 31, No. 11. November 1988. pp. 1268-1287. Google ScholarDigital Library
- Fenton. N. How Effective are Software Engineering Methods? Journal of Systems and Software, Vol. 22. No. 2. 1993. pp. 141-146. Google ScholarDigital Library
- Fromkin, V. and Rodman, R. An Introduction to Language, Fourth Edition. Holt. Rinehart and Winston. New York, 1988, 460 pages. Google ScholarDigital Library
- Hall, W. E. and Zweben. S. H. The Cloze Procedure and Software Comprehensibility Measurement. IEEE Transactions on Software Engineering, Vol. SE-12. No. 5, 1986, pp. 608-623. Google ScholarDigital Library
- Ibrahim, A. M. Acronyms Observed. IEEE Transactions on Professional Communication, Vol. 32, No. 1, 1989. pp. 27- 28.Google ScholarCross Ref
- Keller, D. A. Guide to Natural Naming. ACM SIGPLAN Notices, Vol. 25, No. 5, May 1990, pp. 95-102. Google ScholarDigital Library
- Laitinen, K. and Seppänen, V. Principles for Naming Program Elements, A Practical Approach to Raise Informativity of Programming. In: Part I of Proceedings of InfoJapan'90 International Conference, Information Processing Society of Japan, 1990, pp. 79-86.Google Scholar
- Laitinen, K. and Mukari, T. DNN-Disciplined Natural Naming. A Method for Systematic Name Creation in Software Development. In: Proceedings of 25th Hawaii International Conference on System Sciences, Vol. II: Software Technology, IEEE Computer Society Press. Los Alamitos. California, 1992. pp. 91-100.Google Scholar
- Laitinen, K. Document Classification for Software Quality Systems. ACM SIGSOFT Software Engineering Notes, Vol. 17, No. 4, Oct. 1992, pp. 32-39. Google ScholarDigital Library
- Logsdon, D. and Logsdon, T. The Curse of the Acronym. In: Proceedings of the International Professional Communications Conference. IEEE. 1986. pp. 145-152.Google Scholar
- Page-Jones, M. The Practical Guide to Structured Systems Desing, Second Edition, Prentice Hall. Englewood Cliffs, 1988. 249 pages. Google ScholarDigital Library
- ReaGeniX. ReaGeniX: Real-Time Application Generator-User's Manual, VTT Electronix, Oulu, Finland. 1994, 32 pages.Google Scholar
- Sheppard, S. B., Curtis, B., Milliman, P., and Love, T. Modern Coding Practices and Programmer Performance. Computer, Vol. 12. No. 12. 1979. pp. 41-49.Google Scholar
- Shneiderman, B. Software Psychology, Human Factors in Computer and Information Systems. Winthrop Publishers. Cambridge. Massachusetts. 1980. 320 pages. Google ScholarDigital Library
- Teasley, B. E. The Effects of Naming Style and Expertise on Program Comprehension. International Journal of Human-Computer Studies, Vol. 40. No. 5, 1994. pp. 757-770. Google ScholarDigital Library
- Weiser, M. and Shneiderman, B. Human Factors of Computer Programming. In: Handbook of Human Factors. Salvendys, G. (editor), John Wiley and Sons, New York. 1987, pp. 1398-1415.Google Scholar
- Weissman, L. M. A Methodology for Studying the Psychological Complexity of Computer Programs. PhD-Thesis. Department of Computer Science, University of Toronto, 1974, 231 pages. Google ScholarDigital Library
- Welsh, J. and Han, J. Software Documents: Concepts and Tools. Software - Concepts and Tools, Vol. 15, No. 1, 1994, pp. 12-25.Google Scholar
- Wittgenstein, L. Philosophical investigations, Basil Blackwell, Oxford, 1953, 250 pages.Google Scholar
- Yngve, V. H. Linguistics as a Science. Indiana University Press, Indianapolis, 1986, 120 pages.Google Scholar
- Yourdon, E. Modern Structured Analysis. Prentice-Hall, Englewood Cliffs, New Jersey, 1989, 717 pages. Google ScholarDigital Library
Index Terms
- Estimating understandability of software documents
Recommendations
Ontological text mining of software documents
NLDB'07: Proceedings of the 12th international conference on Applications of Natural Language to Information SystemsDocuments written in natural languages constitute a major part of the software engineering lifecycle artifacts. Especially during software maintenance or reverse engineering, semantic information conveyed in these documents can provide important ...
An Exploratory Study on Codes in Heterogeneous Software Documents
Internetware '18: Proceedings of the 10th Asia-Pacific Symposium on InternetwareDifferent kinds of software documents are produced in the life cycle of a software project, such as Bug Reports, Mail Lists, etc. These documents have close relationship with source code, but it is difficult to recover their traceability relationship. ...
Visualizing Software Structure Understandability
ASWEC '14: Proceedings of the 2014 23rd Australian Software Engineering ConferenceSoftware architecture design is known to be driven by the quality attributes we may want to satisfy. Among them, modifiability plays an important role since software maintenance takes the lion's share in the software development costs. However, to ...
Comments