meeting -*- Outline -*-

* adding detail with operation contracts (Larman Ch. 13)
  See also the other references on the syllabus, particularly Chapter 11
  in Bertrand Meyer's book.

  Recall that a system operation is an event identified in the
  system sequence diagram.

  The goal of operation contracts is to have more details for some of
  these events that are complex, perhaps too complex to be written in
  detail in a use case.

------------------------------------------
  ADDING DETAIL WITH OPERATION CONTRACTS
             (Larman, Ch 13)

A contract:

  precondition:
    - says when calls are legal
    - describes domain (pre-state)

  postcondition
    - describes effects of a call
       - instance creation
       - attribute modification
       - associations forms and broken
    - relates pre-state to post-state

Contract C01: makeNewSale

Operation:
    makeNewSale(reg: Register)
Cross Reference: Use Cases: Process Sale

Preconditions:
  - none

Postconditions:
  - A new sale instance s
    is associated with reg
  - attributes of s are initialized
------------------------------------------
        The idea is to view the entire system as a big class.

        The postcondition precondition are logical formulas.

        The clauses and implicitly conjoined (with "and").

        Note: in the book, Larman notes that this is all "obvious",
        and that the vagueness in the final postcondition
        clause isn't a problem.
        But he misses trying to find where the register comes from.
        I think that the UI will be keeping track of it, and can
        supply it; the event will have to provide some identifying
        information it may as well be thought of as the register.

        Larman likes to write postconditions in the past tense...
        but I'd rather they describe the post state in relation to the
        pre-state.

** analogy
*** contracting
        Make analogies to human (legal) contracts.

------------------------------------------
        BENEFITS AND OBLIGATIONS

                Client/           Server/
                Caller         Implementor
==========================================
Precond. |     obligation       assumes
         |        (cost)        (benefit)
         |
Postcond.|      assumes        obligation
         |     (benefit)         (cost)
------------------------------------------

        Q: Is the precondition tested by an operation's
        implementation?
        Not usually, it is instead assumed.
            This avoids slowdown from too much defensiveness.

*** stage and curtain (p. 181)
------------------------------------------
    THE STAGE AND THE CURTAIN (p. 181)

0. Director compares stage setup
   to pile of scripts
1. Take picture of stage
2. Close the curtains (action takes place)
3. Open curtains, compare pre-act picture
   to current stage
------------------------------------------
        0 is like the precondition

** examples
   emphasize the abstract level, at the level of the domain model,
   in which these are described

------------------------------------------

Contract C02: addLineItem

Operation:
   addLineItem(s: Sale,
               itemID: itemID,
               quantity: integer)
Cross Reference: Use Cases: Process Sale

Preconditions:
   - none

Postconditions:
   - 


------------------------------------------
        ... - a new SalesLineItem instance, sli, is associated with s
            - all the existing sales line items associated with s are unchanged
            - sli.quantity equals quantity
            - sli is associated with the corresponding ProductSpecification,
              so that their itemIDs match

        In Larman's version, there is a precondition of:
           "There is a sale underway."
        This seems easier to avoid by having the sale passed in.
        Again, the event will have to identify the sale implicitly, it
           may as well be as follows logically as doing it explicitly.

** level
------------------------------------------
        LEVEL FOR WRITING CONTRACTS

Write contracts at domain model level:
  - objects
  - associations
  - attributes
------------------------------------------

** writing contracts leads to domain model updates (13.6)
   It's common to discover the need for new conceptual classes,
   attributes, and associations.
   And these to the domain model.

** advice (13.7-13.8)
   Larman doesn't really like spending much time on contracts;
   his advice: if it's clear what to do, can avoid them.
------------------------------------------
      ADVICE ABOUT CONTACTS (13.7-13.8)

To make contracts:

1. Identify system operations from SSDs
2. For those that are complex or subtle,
   or whch are not clear, make contracts.
3. Postconditions should describe:
   - instances created or deleted
   - attributes modified
   - associations formed and broken

Describe what, now how.

Remember associations needed
establish a memory of information.her

------------------------------------------
        - Don't give an algorithm.

** relation to test plan
------------------------------------------
         RELATION TO TESTING

Can use contracts to tell what to test

Precondition: describes test inputs
Postcondition: describes when tests pass

------------------------------------------
        JML has some support for this, but not really at this level.

** practice
   Q: Can you write some contracts for some of your system operations?