loading...
 This Article 
   
 Share 
   
 Bibliographic References 
   
 Add to: 
 
Digg
Furl
Spurl
Blink
Simpy
Google
Del.icio.us
Y!MyWeb
 
 Search 
   
Technology of Object-Oriented Languages and Systems (TOOLS 34'00)
Prose + Test Cases = Specifications
Santa Barbara, California
July 30-August 03
ISBN: 0-7695-0774-3
Daniel Hoffman, University of Victoria
Paul Strooper, University of Queensland
The rise of component-based software development has created a need for API documentation. Experience has shown that it is hard to create and maintain precise and readable documentation. Prose documentation can provide a good overview but lacks precision. Formal methods offer precision but the resulting documentation is expensive to write and modify. Worse, few developers have the skill or inclination to read formal documentation.We present a pragmatic solution to the problem of API documentation. We augment the current prose documentation with test cases, including expected outputs, and use the prose plus the test cases as the documentation. Typically, there are one or two simple test cases for each likely question about API behavior. With this approach, the documentation is precise, albeit partial. Consistency between code and documentation is guaranteed by running the test cases. The readability of the test cases is of paramount importance because communication with API users is their primary purpose. We present a test script language that supports compact, readable test cases and generation of test drivers, and illustrate the approach with a detailed case study.
Index Terms:
object-oriented, automated testing, API documentation, formal methods
Citation:
Daniel Hoffman, Paul Strooper, "Prose + Test Cases = Specifications," tools, pp.239, Technology of Object-Oriented Languages and Systems (TOOLS 34'00), 2000
Usage of this product signifies your acceptance of the Terms of Use.