1. CS61B L07 Specification and Documentation (1)Garcia / Yelick Fall 2003 © UCB 2003-09-10  Dan Garcia (www.cs.berkeley.edu/~ddgarcia) Kathy Yelick  (www.cs.berkeley.edu/~yelick) inst.eecs.berkeley.edu/~cs61b/ www.ucwise.org 1 Handout: notes Computer Science 61B Data Structures and Advanced Programming Specification & Documentation Lecture 7

2. CS61B L07 Specification and Documentation (2)Garcia / Yelick Fall 2003 © UCB 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. CS61B L07 Specification and Documentation (3)Garcia / Yelick Fall 2003 © UCB 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; } mymon  myMonth & simplify expr: mymon % 2 == 1 Move common code out of conditional Common code Logic problem: 30 vs. 29 day months What kind of variable name is n ? Logic problem: 30 vs. 29 day months 2 == 1 Move common code out of conditional Common code

4. CS61B L07 Specification and Documentation (4)Garcia / Yelick Fall 2003 © UCB 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++; } Change variable to make modulo expression simple Need to switch answer back to 1- based Change variable to make modulo expression simple Need to switch answer back to 1- based

5. CS61B L07 Specification and Documentation (5)Garcia / Yelick Fall 2003 © UCB 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. CS61B L07 Specification and Documentation (6)Garcia / Yelick Fall 2003 © UCB Method Specifications General form of a method specification /** Short description of method behavior * Parameter description * Return value description */ return_type mname(arg_type1 arg1,…) 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.

7. CS61B L07 Specification and Documentation (7)Garcia / Yelick Fall 2003 © UCB 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 int s 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. CS61B L07 Specification and Documentation (8)Garcia / Yelick Fall 2003 © UCB "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. CS61B L07 Specification and Documentation (9)Garcia / Yelick Fall 2003 © UCB “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. CS61B L07 Specification and Documentation (10)Garcia / Yelick Fall 2003 © UCB “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. CS61B L07 Specification and Documentation (11)Garcia / Yelick Fall 2003 © UCB 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. CS61B L07 Specification and Documentation (12)Garcia / Yelick Fall 2003 © UCB Minimality Minimality: place as few constraints on behavior as possible to give the implementer flexibility Compare: 1.Find any instance of x in a list 2.Find the first instance of x in a list Compare: 1.@modifies this 2.No modifies clauses Which is more minimal? Which is better? –1 is more minimal than 2 in both cases –Which is better, depends

13. CS61B L07 Specification and Documentation (13)Garcia / Yelick Fall 2003 © UCB 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. CS61B L07 Specification and Documentation (14)Garcia / Yelick Fall 2003 © UCB 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. CS61B L07 Specification and Documentation (15)Garcia / Yelick Fall 2003 © UCB 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. CS61B L07 Specification and Documentation (16)Garcia / Yelick Fall 2003 © UCB 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. CS61B L07 Specification and Documentation (17)Garcia / Yelick Fall 2003 © UCB Writing Specifications Consider the problem of removing duplicate characters from a String What does the specification look like? What about the implementation? InputResult aabbacabc aaaa abcbaabc

18. CS61B L07 Specification and Documentation (18)Garcia / Yelick Fall 2003 © UCB 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. CS61B L07 Specification and Documentation (19)Garcia / Yelick Fall 2003 © UCB Note different return types, modifies clauses, method names; what is underdetermined? 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)

20. CS61B L07 Specification and Documentation (20)Garcia / Yelick Fall 2003 © UCB 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 String s or StringBuffer s –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. CS61B L07 Specification and Documentation (21)Garcia / Yelick Fall 2003 © UCB 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. CS61B L07 Specification and Documentation (22)Garcia / Yelick Fall 2003 © UCB 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) – name for Java classes, methods – word or phrase -- italics in output – 1st 2nd A bulleted list Use /** to start specs for javadoc

23. CS61B L07 Specification and Documentation (23)Garcia / Yelick Fall 2003 © UCB 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. CS61B L07 Specification and Documentation (24)Garcia / Yelick Fall 2003 © UCB 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?