1. CSC 395 – Software Engineering Lecture 21: Overview of the Term & What Goes in a Data Dictionary

2. In This Lecture Review software engineering process so far One benefit of software engineering Problems that arise when developing software How software engineering tries to solve them What this means for the data dictionary Approaches that can help fix this How to write documentation that might eventually help someone

3. Eliminating Bugs is (NP-)Hard Halting problem states we cannot develop system that proves if a program halts Also cannot prove program free from bugs People seem to like software that works Also demand program be reliable & not crash This ignores several other basic problems Maintaining software years beyond creation Average programmer’s… unique social skills

4. Software Engineering Task of developing software is impossible And given last slide, we CAN prove this Most incapable of performing the impossible Enable specialization & proficiency development Software engineering includes the client Clients/customers are only source of information Starts with use-cases defining ACTUAL problem Everything flows from these initial use-cases

5. Faults != Good (Software) Companies care about money Not particularly interested in anything else Will not discuss this point further (this is CSC395, not PHI395) Companies act to improve their profitability Faults take time to fix Time == money Bugs therefore take money to fix Companies therefore care about faults

6. Good Software Lifecycles Then performs actions developing solution None of these actions performed alone Interlocking methods check & recheck results Each new action begins by reproving result Uses this check to take next step forward Periodically recheck all of the results Prevents building castles on sand Exposes bugs early

7. What Else Is There? Ambiguity equals

8. Why Ambiguity? Faults can be solved; ambiguity cannot Literally, ambiguity created by lack of solutions Once in existence, destroys everything it touches Ambiguity also cannot be detected Rather ironic if we could develop test, though Software engineering creates laborious process to limit ambiguity Unfortunately, nothing limit this work

9. How SE Avoids Ambiguity Insure all possible cases included Develop scenario after scenario after scenario Language is ambiguous Develop entirely new, precise, language to use Give each symbol & connection specific meaning Require everything live up to this level of precision Ambiguity can be created in translations Require documentation of everything Trace all ideas back to the original problem Document everything at obscene levels

10. Data Dictionary Bad idea Work in English again! Worse idea Leave documentation in programmer’s hand Ugly idea Make documentation main decider of code reuse Good idea Make $%&# certain documentation is perfect Develop precise ways of describing code

11. Details in Data Dictionary Do not discuss implementation details List what someone else needs to use this code Describe class & methods in detail What each can do, why each can do it, limits of where each is defined, & what each cannot do Describe expected values for all parameters and what these values mean (use @param) Describe what a result will be, why it will be that way, and what the result means (use @return) Describe exceptional situations (use @throws)

12. Details in Data Dictionary Document important maintenance information Associations on which class or method relies: what is associated are, why association exists, and importance of association @see class @see #method @see class#method Each of the class’ attributes (fields), value it holds, what value means, limits for which value defined Algorithms to be used in implementation Data structures on which it relies Documentation hidden after design phase Move from javadoc to inside module

13. What About Ambiguity? Previous documentation avoids errors Does not prevent ambiguity from entering debate Use three custom javadoc tags Custom tags documented only when specified on command-line Tags make assumptions explicit If assumptions revisited, allows for proper fixes javadoc -tag pre:cm:“Preconditions:” -tag post:cm:“Postconditions:” –tag inv:cmt: “Invariants:”

14. Assumptions & Restrictions Precondition must be true at method start Calling method responsible for ensuring met Method only defined for these situations Postcondition true when method completes Called method responsible for guaranteeing this Should consider what will happen when precondition not met Enables programming-by-contract Lack of implementation details improves reuse

15. Pre & Post Silly Example /** * Compute & print out square root of a number. * * @param x Value whose square root we use * @pre x ≥ 0. System crashes when not met. * @post x 1/2 printed out on System.err */ public void printSquareRoot(int x) { System.err.println(“…”); }

16. Invariants Invariants define properties met at all times Field values that are somehow linked Range over which field is defined Assumptions about how fields, parameters, or other values used Listed using @inv tag Normally included as part of class definition In limited situations, could also include in method

17. Why List Assumptions? Ambiguity equals

18. Why List Assumptions? Makes code-correctness proofs easier Can feed to theorem provers to automate proof Brings correctness proofs to nearly reasonable levels Removes ambiguities during implementation Clarifies responsibilities and actions in modules Reduces need to understand code before use Greatly reduces maintenance costs & improves reuse