Discovering documentation for Java container classes
Henkel, Johannes ; Reichenbach, Christoph LU
and Diwan, Amer
(2007)
In IEEE Transactions on Software Engineering
33(8).
p.526-543
- Abstract
Modern programs make extensive use of reusable software libraries. For example, we found that 17% to 30% of the classes in a number of large Java applications use the container classes from the java.util package. Given this extensive code reuse in Java programs, it is important for the reusable interfaces to have clear and unambiguous documentation. Unfortunately, most documentation is expressed in English, and therefore does not always satisfy these requirements. Worse yet, there is no way of checking that the documentation is consistent with the associated code. Formal specifications present an alternative which does not suffer from these problems; however, formal specifications are notoriously hard to write. To alleviate this... (More)
Modern programs make extensive use of reusable software libraries. For example, we found that 17% to 30% of the classes in a number of large Java applications use the container classes from the java.util package. Given this extensive code reuse in Java programs, it is important for the reusable interfaces to have clear and unambiguous documentation. Unfortunately, most documentation is expressed in English, and therefore does not always satisfy these requirements. Worse yet, there is no way of checking that the documentation is consistent with the associated code. Formal specifications present an alternative which does not suffer from these problems; however, formal specifications are notoriously hard to write. To alleviate this difficulty, we have implemented a tool which automatically derives documentation in the form of formal specifications. Our tool probes Java classes by invoking them on dynamically generated tests and captures the information observed during their execution as algebraic axioms. While the tool is not complete or correct from a formal perspective we demonstrate that it discovers many useful axioms when applied to container classes. These axioms then form an initial formal documentation of the class they describe.
(Less)
- author
- Henkel, Johannes
; Reichenbach, Christoph
LU
and Diwan, Amer
- publishing date
- 2007-08-01
- type
- Contribution to journal
- publication status
- published
- subject
- keywords
- Algebraic specifications, Program documentation, Specification inference
- in
- IEEE Transactions on Software Engineering
- volume
- 33
- issue
- 8
- pages
- 18 pages
- publisher
- IEEE - Institute of Electrical and Electronics Engineers Inc.
- external identifiers
-
- scopus:34547106298
- ISSN
- 0098-5589
- DOI
- 10.1109/TSE.2007.70705
- language
- English
- LU publication?
- no
- id
- b00f367c-f319-4c93-95e5-7ca447a5b6d1
- date added to LUP
- 2019-03-29 20:26:29
- date last changed
- 2022-04-02 07:40:56
@article{b00f367c-f319-4c93-95e5-7ca447a5b6d1,
abstract = {{<p>Modern programs make extensive use of reusable software libraries. For example, we found that 17% to 30% of the classes in a number of large Java applications use the container classes from the java.util package. Given this extensive code reuse in Java programs, it is important for the reusable interfaces to have clear and unambiguous documentation. Unfortunately, most documentation is expressed in English, and therefore does not always satisfy these requirements. Worse yet, there is no way of checking that the documentation is consistent with the associated code. Formal specifications present an alternative which does not suffer from these problems; however, formal specifications are notoriously hard to write. To alleviate this difficulty, we have implemented a tool which automatically derives documentation in the form of formal specifications. Our tool probes Java classes by invoking them on dynamically generated tests and captures the information observed during their execution as algebraic axioms. While the tool is not complete or correct from a formal perspective we demonstrate that it discovers many useful axioms when applied to container classes. These axioms then form an initial formal documentation of the class they describe.</p>}},
author = {{Henkel, Johannes and Reichenbach, Christoph and Diwan, Amer}},
issn = {{0098-5589}},
keywords = {{Algebraic specifications; Program documentation; Specification inference}},
language = {{eng}},
month = {{08}},
number = {{8}},
pages = {{526--543}},
publisher = {{IEEE - Institute of Electrical and Electronics Engineers Inc.}},
series = {{IEEE Transactions on Software Engineering}},
title = {{Discovering documentation for Java container classes}},
url = {{http://dx.doi.org/10.1109/TSE.2007.70705}},
doi = {{10.1109/TSE.2007.70705}},
volume = {{33}},
year = {{2007}},
}