2003-09-10  Dan Garcia (cs.berkeley/~ddgarcia)

1. Computer Science 61BData Structures and Advanced ProgrammingSpecification & DocumentationLecture 7 2003-09-10  Dan Garcia(www.cs.berkeley.edu/~ddgarcia) Kathy Yelick (www.cs.berkeley.edu/~yelick) inst.eecs.berkeley.edu/~cs61b/www.ucwise.org1 Handout:notes

2. Dos and Don’ts of Programming • How does one learn to write “great code”? • Seeing great code • we try to do in solutions and examples • Seeing bad code • We'll pick some randomly-selected bits and show you what NOT to do…

3. What kind of variable name is n? Logic problem: 30 vs. 29 day months Logic problem: 30 vs. 29 day months Common code Common code 2 == 1 mymon myMonth& simplify expr:mymon % 2 == 1 Move common code out of conditional Move common code out of conditional HW2: Bad Code public IslamicDate (int n) { if (n < 29) { mymon = 1; myday = n; } else { mymon = 1; while (n > 30) { if ((mymon + 1) % 2 == 0){ n = n - 30; ++mymon; } else { n = n - 29; ++mymon; } } } myday = n; }

4. Change variable to make modulo expression simple Change variable to make modulo expression simple Need to switch answer back to 1-based Need to switch answer back to 1-based HW2: Good Code • Divide year into 2-month chunks • Each with 30+29=59 days • After getting the chunk, figure out the month within public IslamicDate (int dayOfYear) { // easier in 0-indexing dayOfYear--; myDay = dayOfYear % 59; myMonth = (dayOfYear / 59) * 2; if (myDay >= 30) { myDay -= 30; myMonth++; } myDay++; myMonth++; }

5. Abstraction by Specification • Benefits of abstraction • Locality • You can understand a piece of a program without reading all of the code involved • Programmers on a project can work independently • E.g., Linux has thousands of programmers • Modifiability: can change an implementation without changing the parts of the program that use it • Especially useful for tuning the performance • E.g., someone discovers new algorithm for “ranking pages” graph partitioning

6. The syntactic part of the specification, called the method header or signature. This is part of the program. The semantic part of the specification call the procedure header or signature. This is part of the program. Method Specifications • General form of a method specification /** Short description of method behavior * Parameter description * Return value description */ return_type mname(arg_type1 arg1,…)

7. What Information Goes in Spec? • What goes in the semantics (comment) part? • Assumptions about inputs, I.e., .the requires part • Objects/variables that are modified by the method • The overall effect of the method: what it does • What does not go there? • Information already in the signature, e.g., • this method takes two ints and returns an int • Below the line information that is internal to the implementation (at least in public methods) • Variables that are not visible outside, e.g., • “Sets myTemp equal to 0”

8. "Requires" Part • What assumptions does the method make about inputs • Often called a “precondition” • Liskov calls this the “requires” clause • May also be on “this” (e.g,. "@requires this is non-empty") if not in the representation invariant (which need not go in spec) • Something the method writer may assume to be true • Need not check for them (although they can) • Any behavior is legal if called with condition not met • Try to avoid these • Used for simplicity (early in 61B) and performance (hw3) • 61B Javadoc convention: use @requires texthere • Example: * @requires dayOfYear between 1 and 354

9. “Modifies” Part • Specification should explicitly state any objects that are modified • 61B Javadoc convention: use @modifies vars • Example: * @modifies this • What does it mean? • If the specification simply says it modifies object x then it might modify it sometimes, but not always • If the specification says nothing about modifying x, then the implementation may not modify it • In HW3: * @modifies System.out

10. “Effect” Part • The main part of the specification says what the method does. It is broken into pieces. • The short description, usually a “one-liner” • Tells someone if this might be the method they want • The details, tells the user everything they may need to know. Exactly what does the method return as a function of its input parameters. • May appear in parameter or return parts • Note: our specifications written for the user

11. Qualities of Specifications • Minimality: few constraints on behavior • Underdetermined behavior: allows more than one behavior for some input • Deterministic implementation: given the same input, always has the same behavior • Generality: one specification is more general if is allows a larger class of inputs

12. Minimality • Minimality: place as few constraints on behavior as possible to give the implementer flexibility • Compare: • Find any instance of x in a list • Find the first instance of x in a list • Compare: • @modifies this • No modifies clauses • Which is more minimal? Which is better? • 1 is more minimal than 2 in both cases • Which is better, depends

13. Underdetermined Specifications • It is often useful to write a specification that is underdetermined, i.e., for some inputs more than one possible output is allowed • E.g., "find an occurrence of x" doesn’t say which one • E.g., "compute the square root to within some epsilon" • Some people call these “nondeterministic” specifications, but underdetermined is a better term • Why do this? allow more flexibility, to specify the minimal number of constraints necessary • Downside: can make some kinds of testing harder • More “correct” solutions

14. Deterministic Implementations • Even if the specification is underdetermined, the implementation normally is deterministic • E.g., an implementation to choose x probably chooses the first or last, or at least it always chooses the same one • E.g., a square root routine on a given computer will produce the same result every time • Could you write a procedure that behaved differently on different runs, given the same input on the same computer?

15. Generality in Specifications • One specification is more general than another if it allows more inputs • One without “requires” is more general than one with • An exponential procedure is more general than a square procedure • Why is generality good? • It allows you to reuse more programs, which in turn minimized code writing and bug fixing • Is it ever bad? • It can slow down implementations & make code dense

16. Administrivia • Reading assignments • For today : Javadoc (link on portal) • For Friday: ADW Chapter 8, 9 (up through Vectors) • Quiz in 2 weeks: Monday, 2003-09-22 • In-class, multiple-choice, other details to come • Project #1 handed out on Friday, due ~3 wks • UCWISE slow (w/a high load) • We know this and are looking for a fix • Discussion 114 Tue 1-2pm • 80 Barrows 2062 VLSB (effective 9/16)

17. Writing Specifications • Consider the problem of removing duplicate characters from a String • What does the specification look like? • What about the implementation?

18. Mutable vs. Immutable Data • One of the first questions to answer in writing a spec: • Should the input be modified? • Related to that is the question of whether the types of inputs are mutable: • If not, the argument cannot be modified. • Two datatypes in Java for strings: • String is an immutable type • StringBuffer is like a String, but is mutable • Methods to go back and forth (construct one from the other)

19. Removing Duplicates Specifications • Two possible specs (among many) /** Removes duplicate characters from a string * @param s is the string from which duplicates * will be removed * @return a string with the same set of * characters s, but with all duplicates removed. */ public static String duplicatesRemoved(String s) /** Removes duplicate characters from a string * @param sb is modified by removing any * duplicate characters, possibly changing the * order of other characters. * @modifies sb */ public static void removeDuplicates(StringBuffer sb) • Note different return types, modifies clauses, method names; what is underdetermined?

20. Mutable vs. Immutable Again • Consider writing the String version • Still may use StringBuffer internally. Why? public static String duplicatesRemoved(String s) { StringBuffer sb = new StringBuffer(s); // …do modifications on sb… return sb.toString(); } • HW3 has a similar specification: you may use either Strings or StringBuffers • Don’t worry about speed or memory (for this hw) • Do worry about simplicity of your code • Many requires clauses (or preconditions) in HW3 specs

21. Implementation Strategy • Move from left to right • Keep track of a position (i) and a character to look for (at i) • Look to the right (index j) for other occurrences of this character • If one is found, replace with character from end and shorten StringBuffer by 1 a b a b e a b e b a b e • Lots of care required…

22. Javadoc • javadoc is a program that formats your comments and builds web pages • E.g., from Lecture #1: javadoc HelloWorld.java will produce web page • Based on HTML (don’t need to know much) • <code>name</code> for Java classes, methods • <i>word or phrase</i> -- italics in output • <ul> <li> 1st <li> 2nd </ul> A bulleted list • Use /** to start specs for javadoc

23. Class Specification • The specification of a class contains • High level description of the class • Specifications for each method (public ones seen) • Descriptions of any public fields, variables, exceptions • In addition, each file should contain • @author AuthorName • @version VersionNumber (if you wish) • Javadoc Demo (if time)

24. Peer Instruction: Specifications • public void foo(int x) {x=3;} you should write @modifies x • If a spec says it modifies x, it always modifies x • removeDuplicates is just like set manipulation on chars • Generality in specs is always good • Simple math (like sqrt(10)) is machine-to-machine deterministic (answer is the same… it's Java!) • Identical redundant code should be consolidated 1 : 1 2 : 2 3 : 3 4 : 4 5 : 5 6 : 6 7 : 0 How many of these are TRUE statements?