Lecture 4: VALIDATING Your Design

Why should I learn about marketing? I’m in CSC to avoid this! MKT 101 – Introduction to Marketing Lecture 4:VALIDATING Your Design

Today’s Goal • Learn to validate & fix designs before coding • What matters in comments & how these can help • Techniques & tricks to avoid writing useless code • Javadoc v. regular comments: why have both? • Why both types of comments rely on marketing • Why is this vital for testing the proposed solution?

Today’s Goal • Learn to validate & fix designs before coding • What matters in comments & how these can help • Techniques & tricks to avoid writing useless code • Javadoc v. regular comments: why have both? • Why both types of comments rely on marketing • Why is this vital for testing the proposed solution? Weeks of coding makes up for minutes of planning

How My Homies Roll

How My Homies Roll Already made #YouSucka trending topic

Reactions to Your Code Passion Threshold Suck Threshold

Intuitive Is Key • Making people think is preying on their weakness • Explicitly state details needed to use code • People will assume that everything has purpose • Male nipples, appendix, Matt still talked about • If it serves no purpose, why would it be created? • Guessing game createdfrom unused parameters • Don't make user probe what return value means

Intuitive Is Key It returned 5. What the $#&@#* does5mean? • Making people think is preying on their weakness • Explicitly state details needed to use code • People will assume that everything has purpose • Male nipples, appendix,Mattstill talked about • If it serves no purpose, why would it be created? • Guessing game created from unused parameters • Don't make user probewhat return value means

Intuitive Is Key I DEFINITELY need another drink… • Making people think is preying on their weakness • Explicitly state details needed to use code • People will assume that everything has purpose • Male nipples, appendix,Mattstill talked about • If it serves no purpose, why would it be created? • Guessing game created from unused parameters • Don't make user probewhat return value means

What To Do With Your Design • Move on to next step: write your javadoc • Validate your thinking by forcing communication • Performs test that you are clear what method does • Team development easier, since method use known • If done well, will find helps develop 1st test set

What To Do With Your Design • Move on to next step: write your javadoc • Validate your thinking by forcing communication • Performs test that you are clear what method does • Team development easier, since method use known • If done well, will find helps develop 1sttest set

But We Cannot Document Yet! • Of course, do not yet know details such as… • How method is coded or calls it makes • Which of the class’s fields used within method • How it computes result to get return value • Given an input, why specific algorithm used • javadoc does NOT need & should not include it • You may (or should be asking yourself): Why?

Why Not Include Details? • You writecode once… • This is goal, idea is to solve problems not write code • Writing code is work & laziness means minimizing this • Once code bug free, do not want to look at it again • …but read comments often • If javadoc duplicates code, could just read code • Only provide what users need

What Should Comments Say? • javadoc works with design & does not repeat it • For each class what instances do & where to use • What a method does & when it should be called • Given a methods actions, what method’s results are • Meaning of return values & any special “magic” values • For each real error: when exception will be thrown • How to call method including examples (with return)

Good javadoc /** * Perform the basic work needed when a button is * pushed. This will illuminate the light in the * button. The first time a button is hit it will * also send a message to the elevator controller. */ public void pushButton() { /* Code goes here… */ }

How Does javadoc Test Design? • What if do not know enough to write javadoc? • Can you write code you cannot describe what it does?

How Does javadoc Test Design? • What if do not know enough to write javadoc? • Can you write code you cannot describe what it does? Hint:

How Does javadoc Test Design? • What if do not know enough to write javadoc? • Can you write code you cannot describe what it does? Hint: Your Design Sucks Donkey Balls

Is This Method Really Usable?

What is the Goal Again? • Javadoc!= Java and should not be confused • If comments are good, easier to understand than Java • Only details users need to use method or class • For this to work must make sell its simplicity • Show important connections to well-known examples @see class @see #method @see class#method • Explicitly state any "magic" param or return values • Provide examplesto clarify how it will work

Now This I Can Use

Other Details To Describe • State all assumptions to prevent future bugs • When calling this method, what else will happen?

Other Details To Describe • State all assumptions to prevent future bugs • When calling this method, what else will happen? • Any assumptions upon which method relies

Other Details To Describe • State all assumptions to prevent future bugs • When calling this method, what else will happen? • Any assumptions upon which method relies • Once method completes, details needed for later

Programming By Contract • Precondition true at start when method called • Ensuring these met responsibility of calling method • Postconditions true at end of the method call • Guaranteeing this responsibility of called method • Only if preconditions met must this happen, however

Good Javadoc Example /** * Perform the basic work needed when a button is * pushed. This will illuminate the light in the * button. The first time a button is hit it will * also send a message to the elevator controller.<br/> * * Precondition: lit.isOff(); controller is set<br/> * * Postcondition: !lit.isOff() && * request sent to elevator controller */public void pushButton() {}

What's Next? • Could start to write code at this point in project • But doing this means still may find many bugs • Fixing these hard if calling many other methods • Ideal if we could 1stcheck that method actually works • Remember key trait of successful programmers

Successful Programmers • Could start to write code at this point in project • But doing this means still may find many bugs • Fixing these hard if calling many other methods • Ideal if we could 1stcheck that method actually works • Remember key trait of successful programmers

Outlining a Method • Write pseudocodeoutline of how method works • Can be written assuming other methods they work • Can ignore coding details, so simpler & easier to write • Once done writing, tests check algorithm works • Fix errors BEFORE coding to limit debugging needs • Can then make the algorithm into comments • Check code against comment, since that passed tests • Plain English description makes reading code easier

Outlining a Method • How to write algorithm: what details important? • Can skip punctuation of any sort:this is not code • Should include major loops, but can write in English • Important to translate: each action to take is explicit • Can write “swap values” or group assignments • Using shorthand fine, but translation to code clear

Pseudocode Needs More Detail

Pseudocode Needs Less Detail

Heated Handlebars

For Next Lecture • Week #2 homework available on Angel page • Due by 5:00PM Tuesday • Submit assignment via e-mail & (possibly) paper • Reading for Friday linked to from Angel schedule • Discuss range of possible tests to perform • How often to test code as we are writing it • Present methods of handling failed test

Lecture 4: VALIDATING Your Design