ANU COMP2110 Software Design in 2003 Lecture 10Slide 1 COMP2110 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 COMP2110 Software Design in 2003 Lecture 10Slide 2 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 COMP2110 Software Design in 2003 Lecture 10Slide 3 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 COMP2110 Software Design in 2003 Lecture 10Slide 4 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? Best generated by tools e.g. short, Javadoc } Signature

ANU COMP2110 Software Design in 2003 Lecture 10Slide 5 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

ANU COMP2110 Software Design in 2003 Lecture 10Slide 6 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 COMP2110 Software Design in 2003 Lecture 10Slide 7 Contract violations – whose fault? Precondition violation = bug in client (caller) Postcondition violation = bug in supplier It's as simple as that!

ANU COMP2110 Software Design in 2003 Lecture 10Slide 8 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 COMP2110 Software Design in 2003 Lecture 10Slide 9 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)

ANU COMP2110 Software Design in 2003 Lecture 10Slide 10 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 COMP2110 Software Design in 2003 Lecture 10Slide 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 COMP2110 Software Design in 2003 Lecture 10Slide 12 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 COMP2110 Software Design in 2003 Lecture 10Slide 13 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 COMP2110 Software Design in 2003 Lecture 10Slide 14 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 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 return True if a new resource was created, otherwise return False

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