Verifiable source code documentation in controlled natural language

Tobias Kuhn, Alexandre Bergel

Research output: Contribution to JournalArticleAcademicpeer-review

Abstract

Writing documentation about software internals is rarely considered a rewarding activity. It is highly time-consuming and the resulting documentation is fragile when the software is continuously evolving in a multi-developer setting. Unfortunately, traditional programming environments poorly support the writing and maintenance of documentation. Consequences are severe as the lack of documentation on software structure negatively impacts the overall quality of the software product. We show that using a controlled natural language with a reasoner and a query engine is a viable technique for verifying the consistency and accuracy of documentation and source code. Using ACE, a state-of-the-art controlled natural language, we present positive results on the comprehensibility and the general feasibility of creating and verifying documentation. As a case study, we used automatic documentation verification to identify and fix severe flaws in the architecture of a non-trivial piece of software. Moreover, a user experiment shows that our language is faster and easier to learn and understand than other formal languages for software documentation.

Original languageEnglish
Pages (from-to)121-140
Number of pages20
JournalScience of Computer Programming
Volume96
Issue numberP1
DOIs
Publication statusPublished - 15 Dec 2014
Externally publishedYes

Fingerprint

Formal languages
Engines
Defects
Experiments

Keywords

  • Controlled natural language
  • Metamodelling
  • Moose
  • Pharo

Cite this

@article{2a88635ec23241a8be2ce0d0524872ff,
title = "Verifiable source code documentation in controlled natural language",
abstract = "Writing documentation about software internals is rarely considered a rewarding activity. It is highly time-consuming and the resulting documentation is fragile when the software is continuously evolving in a multi-developer setting. Unfortunately, traditional programming environments poorly support the writing and maintenance of documentation. Consequences are severe as the lack of documentation on software structure negatively impacts the overall quality of the software product. We show that using a controlled natural language with a reasoner and a query engine is a viable technique for verifying the consistency and accuracy of documentation and source code. Using ACE, a state-of-the-art controlled natural language, we present positive results on the comprehensibility and the general feasibility of creating and verifying documentation. As a case study, we used automatic documentation verification to identify and fix severe flaws in the architecture of a non-trivial piece of software. Moreover, a user experiment shows that our language is faster and easier to learn and understand than other formal languages for software documentation.",
keywords = "Controlled natural language, Metamodelling, Moose, Pharo",
author = "Tobias Kuhn and Alexandre Bergel",
year = "2014",
month = "12",
day = "15",
doi = "10.1016/j.scico.2014.01.002",
language = "English",
volume = "96",
pages = "121--140",
journal = "Science of Computer Programming",
issn = "0167-6423",
publisher = "Elsevier",
number = "P1",

}

Verifiable source code documentation in controlled natural language. / Kuhn, Tobias; Bergel, Alexandre.

In: Science of Computer Programming, Vol. 96, No. P1, 15.12.2014, p. 121-140.

Research output: Contribution to JournalArticleAcademicpeer-review

TY - JOUR

T1 - Verifiable source code documentation in controlled natural language

AU - Kuhn, Tobias

AU - Bergel, Alexandre

PY - 2014/12/15

Y1 - 2014/12/15

N2 - Writing documentation about software internals is rarely considered a rewarding activity. It is highly time-consuming and the resulting documentation is fragile when the software is continuously evolving in a multi-developer setting. Unfortunately, traditional programming environments poorly support the writing and maintenance of documentation. Consequences are severe as the lack of documentation on software structure negatively impacts the overall quality of the software product. We show that using a controlled natural language with a reasoner and a query engine is a viable technique for verifying the consistency and accuracy of documentation and source code. Using ACE, a state-of-the-art controlled natural language, we present positive results on the comprehensibility and the general feasibility of creating and verifying documentation. As a case study, we used automatic documentation verification to identify and fix severe flaws in the architecture of a non-trivial piece of software. Moreover, a user experiment shows that our language is faster and easier to learn and understand than other formal languages for software documentation.

AB - Writing documentation about software internals is rarely considered a rewarding activity. It is highly time-consuming and the resulting documentation is fragile when the software is continuously evolving in a multi-developer setting. Unfortunately, traditional programming environments poorly support the writing and maintenance of documentation. Consequences are severe as the lack of documentation on software structure negatively impacts the overall quality of the software product. We show that using a controlled natural language with a reasoner and a query engine is a viable technique for verifying the consistency and accuracy of documentation and source code. Using ACE, a state-of-the-art controlled natural language, we present positive results on the comprehensibility and the general feasibility of creating and verifying documentation. As a case study, we used automatic documentation verification to identify and fix severe flaws in the architecture of a non-trivial piece of software. Moreover, a user experiment shows that our language is faster and easier to learn and understand than other formal languages for software documentation.

KW - Controlled natural language

KW - Metamodelling

KW - Moose

KW - Pharo

UR - http://www.scopus.com/inward/record.url?scp=84908224340&partnerID=8YFLogxK

UR - http://www.scopus.com/inward/citedby.url?scp=84908224340&partnerID=8YFLogxK

U2 - 10.1016/j.scico.2014.01.002

DO - 10.1016/j.scico.2014.01.002

M3 - Article

VL - 96

SP - 121

EP - 140

JO - Science of Computer Programming

JF - Science of Computer Programming

SN - 0167-6423

IS - P1

ER -