COMP 2110 Software Design in 2004 Lecture 12

COMP 2110 Software Design in 2004 Lecture 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 ANU COMP 2110 Software Design in 2003 Lecture 10 Slide 1

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 ANU COMP 2110 Software Design in 2003 Lecture 10 Slide 2

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 ANU COMP 2110 Software Design in 2003 Lecture 10 Slide 3

Routine interfaces • The information a client (caller) needs • What the routine does, not how it does it • • • Name (well-chosen) Return type Argument types Roles of arguments One line description Contract? } Signature • Best generated by tools e. g. short, Javadoc ANU COMP 2110 Software Design in 2003 Lecture 10 Slide 4

2. Contracts • See Meyer Object-Oriented Software Construction Chapter 11 (p. 331 ff) • Ideas come from formal verification – can lead to formal correctness proofs • Doesn't have to go that far ANU COMP 2110 Software Design in 2003 Lecture 10 Slide 5

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. ” ANU COMP 2110 Software Design in 2003 Lecture 10 Slide 6

Contract violations – whose fault? • Precondition violation = bug in client (caller) • Postcondition violation = bug in supplier It's as simple as that! ANU COMP 2110 Software Design in 2003 Lecture 10 Slide 7

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 ANU COMP 2110 Software Design in 2003 Lecture 10 Slide 8

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 also loop invariants and variants: see notes for COMP 1110 and COMP 2100) ANU COMP 2110 Software Design in 2003 Lecture 10 Slide 9

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. ) ANU COMP 2110 Software Design in 2003 Lecture 10 Slide 10

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 ANU COMP 2110 Software Design in 2003 Lecture 10 Slide 11

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. ANU COMP 2110 Software Design in 2003 Lecture 10 Slide 12

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 ANU COMP 2110 Software Design in 2003 Lecture 10 Slide 13

Good and bad pseudocode (From Steve Mc. Connell: Code Complete) Increment resource number by 1 allocate a dlg struct using malloc Keep track of number of resources in use if malloc returns NULL then return 1 If another resource is available then invoke Osrsrc_init to initialise a resource for the operating system set *h. Rsrc. Ptr equal to resource number Allocate a resource structure If a dialog box structure could be allocated then Note that one more resource is in use return 0 Initialise the resource Store the resource number end if return True if a new resource was created, otherwise return False ANU COMP 2110 Software Design in 2003 Lecture 10 Slide 14

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) ANU COMP 2110 Software Design in 2003 Lecture 10 Slide 15