CMSC 433 – Programming Language
Technologies and Paradigms
Spring 2007
Documentation
Feb. 20, 2007
2
Software Specifications
• A specification defines the behavior of an abstraction
•This is the contract between user and provider
– Provider’s code must implement the specification
– Providers are free to change the implementation
• So long as the new code meets the specification
– Users who depend only on specification won’t have trouble
• Don’t rely on implementation
• Black box testing essentially checks compliance of an
implementation with its specification
3
Good Specifications are Hard to Write
• Very difficult to get people to write specifications
– Even harder to keep them up to date
• Having specifications in a separate document from
code almost guarantees failure
– Rationale for Javadoc: extract a standalone
specification from the code and embedded comments
• Hard to accurately and formally capture all
properties of interest
– Always finding important details not specified
4
Specifications Help You Write Code
• Lots of subtle algorithms and data structures
– Internal specs/invariants vital to correct implementation
• Example: Binary Search Tree
– All nodes reachable from left child have smaller key
than current node
– All nodes reachable from right child have larger key
than current node
