1. Improved software quality through semantic descriptions (Skutt) Karlstad University Dept. of Computer Science 2000-05-09 Semla Design Method for use in Skywalker A Design Method with a Focus on Semantic Descriptions Karlstad University Ericsson Infotech AB NUTEK

2. Karlstad University Dept. of Computer Science Semla 2 page 2 Course Overview Part 1: Data abstractions –Data structures and concepts Part 2: Internal and external contracts –Weak external contracts, for use by others –Strong internal contracts, for use by ourselves Part 3: Invariants –Example and discussion

3. Karlstad University Dept. of Computer Science Semla 2 page 3 Before We Start System development is a team work Which is better? –Microscopic view: “I should always protect my module against crashes” –Macroscopic view “I should always protect the system against defects” The overall goal is to make the system work well That can be done by –Avoiding errors in the first place –Detecting and removing errors that sneak in Surviving an error is not a goal –Errors should be detected and removed

4. Improved software quality through semantic descriptions (Skutt) Karlstad University Dept. of Computer Science 2000-05-09 Part 1 Data abstractions

5. Karlstad University Dept. of Computer Science Semla 2 page 5 An example: A web connection We want to model a possible connection across a network –The other side may or may not be connected –If connected, the other side has a defined user name which is copied across to our program String* otherUser WebConnection the World Wide Web The other side userName

6. Karlstad University Dept. of Computer Science Semla 2 page 6 Data abstractions This is one possible model of a Web connection I want to expose the property otherUser There is a difference between –an empty user name, means "user name not known" –no user name, means "there is no other party" Suggest a class interface String* otherUser WebConnection

7. Karlstad University Dept. of Computer Science Semla 2 page 7 First attempt Class interface –String* getOtherUser(); What is the mental process? –Return whatever is stored in the object –The user of the object needs to be aware of the storage conventions String* otherUser WebConnection String* getOtherUser();

8. Karlstad University Dept. of Computer Science Semla 2 page 8 Contract for the first attempt Precondition: –true Postcondition: –result = the value of the otherUser variable What is gained in abstraction? –Nothing, possibly R/O –You might as well access the data directly String* otherUser WebConnection String* getOtherUser(); Calling style theOther = connection->getOtherUser(); if (theOther != NULL) doSomethingWith(theOther); else handleTheNoUserCase();

9. Karlstad University Dept. of Computer Science Semla 2 page 9 Second attempt Class interface –bool hasOtherUser(); –String* getOtherUser(); What is the mental process? –Define the other user as a concept Either there is one or there is not –The user of this object does not need to be aware of the storage conventions He works with the concept of ”another user" rather than with a stored value (attributes not disclosed) WebConnection bool hasOtherUser(); String* getOtherUser();

10. Karlstad University Dept. of Computer Science Semla 2 page 10 First contract for the second attempt Precondition for hasOtherUser: –true Postcondition for hasOtherUser: –result = true if there is another user defined, else false What is the gain in abstraction? –The fact that there may or may not be an "other user" becomes a property of the class, not a value of a variable –No knowledge of the variable is needed to get the answer –The answer may in fact be evaluated WebConnection bool hasOtherUser(); String* getOtherUser();

11. Karlstad University Dept. of Computer Science Semla 2 page 11 Consequences of the second attempt Possible calling style if (connection->hasOtherUser()) { theOther = connection->getOtherUser(); doSomethingWith(theOther); } else handleTheNoUserCase(); WebConnection bool hasOtherUser(); String* getOtherUser();

12. Karlstad University Dept. of Computer Science Semla 2 page 12 Second contract for the second attempt Precondition for getOtherUser(); –Alt 1: true –Alt 2: hasOtherUser() Postcondition for getOtherUser(); –Alt 1a: the value of otherUser is returned What is wrong with that? –Alt 1b: if hasOtherUser() then the name of the other user is returned, else NULL is returned Is that good? –Alt 2: the name of the other user is returned Is that good? WebConnection bool hasOtherUser(); String* getOtherUser();

13. Karlstad University Dept. of Computer Science Semla 2 page 13 Consequences of alt 1 Alt 1 allows the calling style from the first attempt theOther = connection->getOtherUser(); if (theOther != NULL) doSomethingWith(theOther); What is good with that? What is bad with that? Alt 1 can be called a weak contract –Alt 2 is a strong contract WebConnection bool hasOtherUser(); String* getOtherUser();

14. Improved software quality through semantic descriptions (Skutt) Karlstad University Dept. of Computer Science 2000-05-09 Part 2 Internal and external contracts

15. Karlstad University Dept. of Computer Science Semla 2 page 15 Contracts - Allocation of Responsibilities A contract specifies obligations and benefits Client Supplier BenefitObligation PayGet goods Supply goodsGet money The supplier only needs to fulfill his obligations if the client fulfills his

16. Karlstad University Dept. of Computer Science Semla 2 page 16 Contracts - Preconditions and Postconditions In module design, the obligations and benefits of the contracts are regulated through preconditions and postconditions Method Precondition Postcondition SupplierClient Obligation: Assure precondition Benefit: Assume postcondition Benefit: Assume precondition Obligation: Assure postcondition

17. Karlstad University Dept. of Computer Science Semla 2 page 17 The structure of a module External module interface Internal module interfaces

18. Karlstad University Dept. of Computer Science Semla 2 page 18 Examples of interfaces defineOtherUser(String *otherUser); –to be called from a client system –potential problem? otherUser == NULL? setCode(String *code); –to be called directly from a user interface –potential problem? illegal value entered? –where should the check be done –how is that reflected in the contract int getElement(int elementNumber); –to be called from a client module –potential problem? index out of bounds

19. Karlstad University Dept. of Computer Science Semla 2 page 19 What is the difference? Your module may be exposed to clients that are –yourself –trusted friends –colleagues within the same project –colleagues from other projects –external customers –end users, through a user interface Who do you trust? –To whom do you expose a strong or a weak contract? A correct call is always your client’s responsibility –Even weak contracts fall back on the client –Error messages or exceptions must be caught by the client or user.

20. Karlstad University Dept. of Computer Science Semla 2 page 20 The implication of a contract Precondition A precondition is a Boolean expression that must be true when an operation is called. A precondition is not a guard condition; it is a condition that must be true, not a way to optionally execute an operation. The condition is supposed to be true, and anything else is a programming error. It can be useful to test the precondition at the beginning of the operation for reliability, but this is in the nature of debugging a program. Postcondition A postcondition is a Boolean expression that must be true after the execution of an operation completes. It is an assertion, not an executable statement. The condition is supposed to be true, and anything else is a programming error. It can be useful to test the postcondition after the operation, but this is in the nature of debugging a program.

21. Karlstad University Dept. of Computer Science Semla 2 page 21 The implication of a contract (cont’d) Precondition It is the responsibility of the caller to satisfy the condition. It is not a condition that the receiver should have to check. If the condition is not satisfied, no statement can be made about the integrity of the operation of the system. It is liable to utter failure. Postcondition A postcondition is a constraint on the implementor of an operation. Depending on the exact form of the expression, it might be possible to verify it automatically in advance. Source: Rumbaugh, J., Jacobson, I., Booch, G., The UML Reference Manual, Addison Wesley 1999. Parts of the descriptions have been rearranged to highlight similarities and differences.

22. Karlstad University Dept. of Computer Science Semla 2 page 22 When to use strong contracts? Strong contracts is the default mode Use strong contracts for –internal interfaces the client is yourself, whom you trust to write good code the client is a trusted friend or colleague the client is from your project the client is from your organization any broken contract will be managed within the organization and corrected –external programmable interfaces (APIs) requires a very clear documentation broken contracts are the responsibility of the client but may be detected in the delivered code

23. Karlstad University Dept. of Computer Science Semla 2 page 23 When to use weak contracts? Weak contracts are the exception Use weak contracts for –unforeseeable internal problems hardware problems communications problems –very costly preconditions matrix inversion checking the precondition = doing the job –end user communication the weak contract may be implemented in a shield cases where the end user may interfere –web interface –concurrent processing another thread may break the precondition after the check

24. Karlstad University Dept. of Computer Science Semla 2 page 24 A function specification attempt

25. Karlstad University Dept. of Computer Science Semla 2 page 25 A modified function specification connectionPossible –Description Tests if the caller is allowed to make a call –Syntax connectionPossible(int type, String *address, bool URL) –Parameters typetype of call according to list addressthe address to connect to URLtrue if address is a URL needing to be parsed –Precondition type is a legal number, address is not the 0 pointer –Postcondition returns true if the connection is allowed, else false comments? –Preconditions are related to this call –First part is a logical constraint, second part is a physical constraint

26. Karlstad University Dept. of Computer Science Semla 2 page 26 Example Array A class Array is an abstraction of a C int array –an Array instance has a fixed lower index: 0 –an Array instance has a fixed number of elements defined at creation time Constructor: –Array() Precondition: true Postcondition: number of elements = 0 –Array(int n) Precondition: n >= 0 Postcondition: number of elements = n, all elements = 0

27. Karlstad University Dept. of Computer Science Semla 2 page 27 Example Array Properties for Array a –int size() Precondition: true (*) Postcondition: the number of elements in the array is returned Data access and assignment for Array a –a[i] Precondition: i >= 0 and i < a.size() Postcondition: a reference to the element at index ’i’ has been returned Usage of data access and assignment of Array a –Data access n = a[i] –Data assignment a[i] = n (*) The precondition true will not be written out. No precondition = true

28. Karlstad University Dept. of Computer Science Semla 2 page 28 Implementation details for Array Assume the data storage is through a pointer –int *_data; Constructor Array(int n) { // assign storage for i elements of int _data = new int[n]; // initialize the elements to zero for (int i = 0; i < n; i++) _data[i] = 0;} No promises are given for illegal values of n –Let the program crash if it wants. It is the client’s problem. –Make the program crash if you want. Constructor Array(int n) { ASSERT (n >= 0)// validate the precondition // the rest of the constructor

29. Karlstad University Dept. of Computer Science Semla 2 page 29 More implementation details for Array Data access int &operator[](int i) { return _data[i]; } No promises are given for illegal values of i –Let the program crash if it wants. It is the client’s problem –Make the program crash if you want int &operator[](int i) { ASSERT ( (i >= 0) && (i < size()) ) return _data[i]; } –Any function called in the ASSERT must be side effect free

30. Improved software quality through semantic descriptions (Skutt) Karlstad University Dept. of Computer Science 2000-05-09 Part 3 Invariants

31. Karlstad University Dept. of Computer Science Semla 2 page 31 An invariant is ”always” true Established at creation Maintained by all functions Every function implementation can always assume that the invariant is true Every function implementation should always restore the invariant {I} means that the invariant is valid here Establish invariant > operation() Maintain invariant operation() Maintain invariant {I}

32. Karlstad University Dept. of Computer Science Semla 2 page 32 Invariant example Document invariants as comments class WebConnection { String *otherUserName;// NULL if no user, else his name } Complicated invariants are documented separately class WebConnection { String *otherUserName; // Invariant: // otherUserName == NULL if no "other user" is defined //*otherUserName == "" means "user exists but not known" }

33. Karlstad University Dept. of Computer Science Semla 2 page 33 Invariants often document implementation issues The exact interpretation of and conventions for otherUserName is a private concern –special values should not be known to the environment –the “no user” case should be conveyed to the client through an abstraction boolean hasUser()

34. Karlstad University Dept. of Computer Science Semla 2 page 34 Are the invariants visible from the outside? The external aspects should be limited to those that are meaningful to the concept described and not tied to the implementation But sometimes there are invariant conditions that are given by the concept defined and independent of the implementation The size of an array is always >= 0 –So the size in the constructor must be >= 0 to establish the invariant –Does not depend on the implementation The size of a list is always >= 0 –So the size must be >= 1 before a removal not to break the invariant Since a removal reduces the size by one which would make a negative size if not >= 1 before The implementation may add more invariants not visible outside –size == 0 _first == NULL

35. Karlstad University Dept. of Computer Science Semla 2 page 35 External and internal invariants External invariant –Type invariant –Abstraction invariant –Relates to the abstraction itself, regardless of implementation –Visible from outside –Documented with the external documentation (API) Internal invariant –Implementation invariant –Tied to the specific implementation –Not visible from outside –Documented in the code only LinkedList add(element) find(element)... LinkedNode 0..1 _ first client External invariant: size() > 0 Internal invariant: _first == NULL the list is empty _first != NULL => _first points to the first element in the list

36. Karlstad University Dept. of Computer Science Semla 2 page 36 An implementation invariant: linked list implementation A linked list head Invariant –_first == NULL or _first points to the first element in the list –_first == NULL the list is empty Implementation –constructor: establish invariant LinkedList() {_first = NULL;} // an empty list LinkedList add(element) find(element)... LinkedNode 0..1 –add: assume invariant at entry, restore invariant before exit add(element) { LinkedNode newNode = new LinkedNode(element); if (_first == NULL) _first = newNode; else appendAtEnd(newNode); } _ first client

37. Karlstad University Dept. of Computer Science Semla 2 page 37 Another implementation invariant: array implementation Data declaration –int *_data; –int _size; Invariant: –_data != NULL –more? Constructor Array(int n) –_data = new int[n]; Array int _size Array(int) operator[](int)... client 1 Possible alternative invariant –if _size > 0 then _data != NULL else _data == NULL Consequences for the constructor Array(int n) –if (n == 0) _data = NULL; else _data = new int[n]; Consequences for the indexing operator operator[](int i) –none, the precondition assures a correct call _ data int

38. Karlstad University Dept. of Computer Science Semla 2 page 38 Relations between invariants and pre- and postcontidions As a main rule, the invariant is always part of all preconditions and all postconditions –follows from the definitions Part of the invariant is normally implementation oriented and the pre- and postconditions client oriented –There is one set of pre- and postcondition of interest to the client –There is another set of pre- and postcondition of interest for the implementation –the precondition for the implementation = the precondition exported to the clients + the (external) invariant for the abstraction + the (internal) invariant for the implementation –Similarly for the postcondition

39. Karlstad University Dept. of Computer Science Semla 2 page 39 Implement a queue using an array Data declaration –int *_data; –int _size; Invariant –_data != NULL –_size = number of used elements –the first element is at _data[0] Stack int _size Array(int) operator[](int)... int 1 Consequence –Positions 0 through size()-1 hold data Removal: remove() –Precondition: size() > 0 –Implementation {for (int i = 1; i < _size; i++) _data[i-1] = _data[i]; // maintains implementation invariant _size = _size - 1;} _ data client

40. Karlstad University Dept. of Computer Science Semla 2 page 40 Are invariants useful? An invariant should be stated explicitly Useful for the design –Forces you to think over what you really want, since you should write it down Useful to maintain consistency over time –Documents your decisions –Helps you not change your mind halfway through Useful to support the implementation –Tells you what you can rely on and what you need to accomplish in addition to the public preconditions and postconditions Useful for error detection –Tests may be activated on the invariants to detect when :-) they are broken