article

Free access

Estimating understandability of software documents

Author:

Kari LaitinenAuthors Info & Claims

ACM SIGSOFT Software Engineering Notes, Volume 21, Issue 4

Pages 81 - 92

https://doi.org/10.1145/232069.232092

Published: 01 July 1996 Publication History

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.

References

[1]

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.

[2]

Carter, B. On Choosing Identifiers. ACM SIGPLAN Notices, Vol. 17, No. 5. May 1982. pp. 54-59.

Digital Library

[3]

Coad, P. and Yourdon. E. Object Oriented Analysis. Prentice-Hall, Englewood Cliffs. New Jersey, 1990. 223 pages.

Digital Library

[4]

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.

Digital Library

[5]

Fenton. N. How Effective are Software Engineering Methods? Journal of Systems and Software, Vol. 22. No. 2. 1993. pp. 141-146.

Digital Library

[6]

Fromkin, V. and Rodman, R. An Introduction to Language, Fourth Edition. Holt. Rinehart and Winston. New York, 1988, 460 pages.

Digital Library

[7]

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.

Digital Library

[8]

Ibrahim, A. M. Acronyms Observed. IEEE Transactions on Professional Communication, Vol. 32, No. 1, 1989. pp. 27- 28.

[9]

Keller, D. A. Guide to Natural Naming. ACM SIGPLAN Notices, Vol. 25, No. 5, May 1990, pp. 95-102.

Digital Library

[10]

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.

[11]

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.

[12]

Laitinen, K. Document Classification for Software Quality Systems. ACM SIGSOFT Software Engineering Notes, Vol. 17, No. 4, Oct. 1992, pp. 32-39.

Digital Library

[13]

Logsdon, D. and Logsdon, T. The Curse of the Acronym. In: Proceedings of the International Professional Communications Conference. IEEE. 1986. pp. 145-152.

[14]

Page-Jones, M. The Practical Guide to Structured Systems Desing, Second Edition, Prentice Hall. Englewood Cliffs, 1988. 249 pages.

Digital Library

[15]

ReaGeniX. ReaGeniX: Real-Time Application Generator-User's Manual, VTT Electronix, Oulu, Finland. 1994, 32 pages.

[16]

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.

[17]

Shneiderman, B. Software Psychology, Human Factors in Computer and Information Systems. Winthrop Publishers. Cambridge. Massachusetts. 1980. 320 pages.

Digital Library

[18]

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.

Digital Library

[19]

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.

[20]

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.

Digital Library

[21]

Welsh, J. and Han, J. Software Documents: Concepts and Tools. Software - Concepts and Tools, Vol. 15, No. 1, 1994, pp. 12-25.

[22]

Wittgenstein, L. Philosophical investigations, Basil Blackwell, Oxford, 1953, 250 pages.

[23]

Yngve, V. H. Linguistics as a Science. Indiana University Press, Indianapolis, 1986, 120 pages.

[24]

Yourdon, E. Modern Structured Analysis. Prentice-Hall, Englewood Cliffs, New Jersey, 1989, 717 pages.

Digital Library

Cited By

Chen CShoga MBoehm B(2019)Characterizing Software Maintainability in Issue Summaries using a Fuzzy Classifier2019 IEEE 19th International Conference on Software Quality, Reliability and Security (QRS)10.1109/QRS.2019.00029(131-138)Online publication date: Jul-2019
https://doi.org/10.1109/QRS.2019.00029
Chen CShoga MLi BBoehm B(2019)Assessing Software Understandability in Systems by Leveraging Fuzzy Method and Linguistic AnalysisProcedia Computer Science10.1016/j.procs.2019.05.051153(17-26)Online publication date: 2019
https://doi.org/10.1016/j.procs.2019.05.051
Rubin ERubin H(2018)Agile Development Processes and Knowledge DocumentationComputer Systems and Software Engineering10.4018/978-1-5225-3923-0.ch058(1433-1453)Online publication date: 2018
https://doi.org/10.4018/978-1-5225-3923-0.ch058
Show More Cited By

Index Terms

Estimating understandability of software documents
1. Software and its engineering
  1. Software creation and management
    1. Software post-development issues
      1. Documentation
2. Theory of computation
  1. Semantics and reasoning
    1. Program semantics

Recommendations

Ontological text mining of software documents
NLDB'07: Proceedings of the 12th international conference on Applications of Natural Language to Information Systems

Documents 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 Internetware

Different 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 Conference

Software 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

Please enable JavaScript to view thecomments powered by Disqus.

Information & Contributors

Information

Published In

cover image ACM SIGSOFT Software Engineering Notes

ACM SIGSOFT Software Engineering Notes Volume 21, Issue 4

July 1996

100 pages

ISSN:0163-5948

DOI:10.1145/232069

Editor:
Will Tracz

Issue’s Table of Contents

Copyright © 1996 Author.

Publisher

Association for Computing Machinery

New York, NY, United States

Publication History

Published: 01 July 1996

Published in SIGSOFT Volume 21, Issue 4

Check for updates

Qualifiers

Article

Contributors

Other Metrics

View Article Metrics

Bibliometrics & Citations

Bibliometrics

Article Metrics

33
Total Citations
View Citations
503
Total Downloads

Downloads (Last 12 months)47
Downloads (Last 6 weeks)14

Reflects downloads up to 24 Nov 2024

Other Metrics

View Author Metrics

Citations

Cited By

Chen CShoga MBoehm B(2019)Characterizing Software Maintainability in Issue Summaries using a Fuzzy Classifier2019 IEEE 19th International Conference on Software Quality, Reliability and Security (QRS)10.1109/QRS.2019.00029(131-138)Online publication date: Jul-2019
https://doi.org/10.1109/QRS.2019.00029
Chen CShoga MLi BBoehm B(2019)Assessing Software Understandability in Systems by Leveraging Fuzzy Method and Linguistic AnalysisProcedia Computer Science10.1016/j.procs.2019.05.051153(17-26)Online publication date: 2019
https://doi.org/10.1016/j.procs.2019.05.051
Rubin ERubin H(2018)Agile Development Processes and Knowledge DocumentationComputer Systems and Software Engineering10.4018/978-1-5225-3923-0.ch058(1433-1453)Online publication date: 2018
https://doi.org/10.4018/978-1-5225-3923-0.ch058
Capiluppi AAjienka NAdams BConstantinou EMens TRobles G(2018)National boundaries and semantics of artefacts in open source developmentProceedings of the 1st International Workshop on Software Health10.1145/3194124.3194131(33-39)Online publication date: 28-May-2018
https://dl.acm.org/doi/10.1145/3194124.3194131
Ukić NMaras JźErić L(2018)The influence of cyclomatic complexity distribution on the understandability of xtUML modelsSoftware Quality Journal10.1007/s11219-016-9351-526:2(273-319)Online publication date: 1-Jun-2018
https://dl.acm.org/doi/10.1007/s11219-016-9351-5
Palma FGonzalez-Huerta JFouni MMoha NTremblay GGuéhéneuc Y(2017)Semantic Analysis of RESTful APIs for the Detection of Linguistic Patterns and AntipatternsInternational Journal of Cooperative Information Systems10.1142/S021884301742001126:02(1742001)Online publication date: Jun-2017
https://doi.org/10.1142/S0218843017420011
Palma FGonzalez-Huerta JMoha NGuéhéneuc YTremblay G(2015)Are RESTful APIs Well-Designed? Detection of their Linguistic (Anti)PatternsService-Oriented Computing10.1007/978-3-662-48616-0_11(171-187)Online publication date: 16-Nov-2015
https://dl.acm.org/doi/10.1007/978-3-662-48616-0_11
Rubin ERubin H(2014)Agile Development Processes and Knowledge DocumentationHandbook of Research on Emerging Advancements and Technologies in Software Engineering10.4018/978-1-4666-6026-7.ch014(309-328)Online publication date: 2014
https://doi.org/10.4018/978-1-4666-6026-7.ch014
Pratap AChaudhary RYadav K(2014)Estimation of software maintainability using fuzzy logic technique2014 International Conference on Issues and Challenges in Intelligent Computing Techniques (ICICT)10.1109/ICICICT.2014.6781331(486-492)Online publication date: Feb-2014
https://doi.org/10.1109/ICICICT.2014.6781331
Mahmoud ANiu N(2014)Supporting requirements to code traceability through refactoringRequirements Engineering10.1007/s00766-013-0197-019:3(309-329)Online publication date: 1-Sep-2014
https://dl.acm.org/doi/10.1007/s00766-013-0197-0
Show More Cited By

View Options

View options

PDF

View or Download as a PDF file.

eReader

View online with eReader.

Login options

Check if you have access through your login credentials or your institution to get full access on this article.

Full Access

Get this Publication

Media

Figures

Other

Tables

View Issue’s Table of Contents