CS61B L07 Specification and Documentation (1)Garcia / Yelick Fall 2003 © UCB 2003-09-10 Dan Garcia...

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.org1 Handout: notes

Computer Science 61BData Structures and Advanced Programming

Specification & Documentation Lecture 7


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…


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


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


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


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.


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”


"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


“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


“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


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


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


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


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?


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


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)


Writing Specifications• Consider the problem of removing duplicate

characters from a String

• What does the specification look like?• What about the implementation?

Input Result

aabbac abc

aaa a

abcba abc


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)


• 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)


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


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…


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


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)


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 : 34 : 45 : 56 : 67 : 0

How many of these are TRUE statements?

CS61B L07 Specification and Documentation (1)Garcia / Yelick Fall 2003 © UCB 2003-09-10 Dan Garcia...

Documents

Transcript of CS61B L07 Specification and Documentation (1)Garcia / Yelick Fall 2003 © UCB 2003-09-10 Dan Garcia...