Download
1 / 15
150 likes | 159 Views
Learn how to write down a detailed design that is good enough for someone else to implement. Topics covered include interfaces, contracts, and pseudocode. Discover guidelines for writing preconditions, class invariants, and the use of pseudocode in the documentation process.
E N D
COMP2110 Software Design in 2004Lecture 12 Documenting Detailed Design • How to write down detailed design. • Good enough that you can let someone else implement it. • This is very hard to do well! Topics: • Interfaces • Contracts • Pseudocode
1. Interfaces • This is not the Java interface concept – a purely abstract class with no implementation • This is also not about user interfaces – more on them in some later lectures • This is about documenting the way a software component interacts with other components • We will cover both classes and routines
Class interfaces • List all public (externally visible) features • Members & methods • Attributes & routines • Queries & commands • Similar to what appears in the box in a UML class diagram
Routine interfaces • The information a client (caller) needs • What the routine does, nothow it does it • Name (well-chosen) • Return type • Argument types • Roles of arguments • One line description • Contract? • Best generated by tools e.g. short, Javadoc } Signature
2. Contracts • See Meyer Object-Oriented Software Construction Chapter 11 (p.331ff) • Ideas come from formal verification – can lead to formal correctness proofs • Doesn't have to go that far
Pre- and Post-conditions • Precondition: What the routine assumes to be true before it starts • Postcondition: What the routine guarantees to be true when it returns • Contract: { pre } body { post } “If you promise to call me with my preconditions satisfied, then I promise to deliver you a final state in which my postconditions are satisfied.”
Contract violations – whose fault? • Precondition violation = bug in client (caller) • Postcondition violation = bug in supplier It's as simple as that!
How strong should preconditions be? • Too many / too strong • “Customer is always wrong” • Routine can't be used • Too few / too weak • “Customer is always right” • Writing the routine becomes impossible Guidelines for writing preconditions: • Must appear in documentation for client code • Must be justifiable from the requirements
Class invariants • Global properties of the class • Must be satisfied by every instance at all times (except briefly during operations) • e.g for a stack: empty = (count = 0) count >= 0 • Creation routine must establish invariant • Contract is now: { pre and inv } body { post and inv } (There are also loop invariants and variants: see notes for COMP1110 and COMP2100)
Contracts as documentation • Add to the less formal description given as part of the interface • Major benefit is to remove duplication: • Supplier does not have to check that the precondition has been satisfied. (That's the client's job.) • Client does not have to check that the postcondition has been satisfied. (That's the supplier's job.)
3. Pseudocode • Halfway between natural language and computer code • Use indenting and informal control structures • Do not use technical language • Do not use details from implementation language.(In other words, the same pseudocode should work for • Eiffel or Java or C++ or Smalltalk • C or Pascal or Fortran or Ada • Bash or Perl or Python or Csh
How to write pseudocode • Break down the body of the routine into steps • Write at the level of intent • Still “What” not “How” but at a lower level of abstraction • Must be at a higher level of abstraction than the finished code • Big idea: The pseudocode becomes the comments in the finished code.
Example: Merge sort if the list has more than one element then divide the list into two equal parts merge sort the first part merge sort the second part while both halves are non-empty do compare their first elements and select the smaller end while copy the remaining elements end if
Keep track of number of resources in use If another resource is available then Allocate a resource structure If a dialog box structure could be allocated then Note that one more resource is in use Initialise the resource Store the resource number end if end if return True if a new resource was created, otherwise return False Good and bad pseudocode (From Steve McConnell:Code Complete) Increment resource number by 1 allocate a dlg struct using malloc if malloc returns NULL then return 1 invoke Osrsrc_init to initialise a resource for the operating system set *hRsrcPtr equal to resource number return 0
More on good pseudocode (and comments) • Think of comments (lines of pseudocode) as paragraph headings in the finished code • Focus on what and why, not how • Don't just repeat what the code does • Always write at the level of intent, not at the level of implementation • Write at a sufficiently low level that writing the code itself will be almost automatic for a skilled programmer with no knowledge of the system or its design (a code monkey)
