CS10, Fall 2009, lab04

Instructor: Phill Conrad
TAs: Esra Kucukoguz, Yiming Li, Murali Yeleswarapu

Primary TA for this lab: Esra Kucukoguz

Important note

Please read all of the instructions before staring this lab—even the section that says "Goals". Here, let me put it in hideously ugly colors, and a different font, in order to try to get your attention.

Read ALL of the instructions before starting!
(Especially the "Goals" and "Overview" sections!)

It will really help if you do. A lot of questions that the TAs and I get are answered here.

Goals

• Reinforce basic concepts of how testing and development support each other
• Reinforce concept of separating user interface from object implementation
• Practice problem solving with multiple classes (QuadraticEqn class that uses Complex)
• Practice developing a command line user interface (with System.out.println, and the Scanner class.)

Collaboration

On this project, you may work in pairs, but if you do, you still each need to turn in a separate submission, and you should indicate in a comment in your code who it was that you worked with.

A reminder that copying code electronically from one person to another is NOT permitted for this assignment—don't email code, or send it back and forth through a chat program, or anything like that. You may look at each others code and discuss each others code, but you may not type for each other, or copy code directly. (You may wonder how we can tell----it is usually typos, and small formatting glitches that are the tell-tale signs of direct code copying)

Another way to say this is—if you work together, you may "share with your mouth and your eyes, but not with your fingers."

Overview

Read this before starting—this gives you the big picture, so that you understand WHY you are doing what you are doing.

The detailed instructions come later on this web page.

In the preliminaries, you'll just copy some code from the course web site into your account.

You'll also see that the

1. In the first part, you'll look over the code you've copied to understand what you have. You'll see that you have:
   • QuadraticEqn, a class for a quadratic equation
   • Complex, a class for a complex number
   • JUnit tests for both of those classes (QuadraticEqnTest and ComplexTest)
   • QuadraticSolver, a class with a main() method that presents a user interface to solve Quadratic equations (even if the solutions are Complex)

   In the detailed instructions for Part 1, we'll guide you through how important it is to learn how to read code, not just write code. We'll point out several things you should notice as you read through these files.

2. In the second part, you'll first go through the ComplexTest class, and look at the test methods, to understand how they work. Many of these are similar to the ones you say in lab02—and a few are new. Then, there are a few places where you need to add some test methods. The instructions below will walk you through doing that.
   
   There are several reasons for asking you to add more JUnit tests.

   • To give you more experience with thinking about testing in general
   • To give you more experience—specifically—with JUnit testing, so that eventually, you'll be able to write a complete set of JUnit tests on your own without any prompting.
   • To get you thinking about the various methods of the Complex class and how they work

3. In the third part, you'll first work through the Complex class until all of its test methods pass, and then through the QuadraticEqn class until all of its test methods pass. It is important to do it in that order, since the QuadraticEqn class depends on the Complex class.

   • This part is about problem solving—we are providing some problems where you have to really think through the solution a bit.
   • It also provides practice with working with a program where the solution involves multiple classes that depend on each other.
4. In the fourth part, you'll first look at the QuadraticSolver, which solves quadratic equations based on user input. There is no code you have to add here—this code is here as an example of how a "real program" can be supported by the work you do on basic classses and unit tests (that is, the work you did on QuadraticEqn, Complex, and its two unit test classes.) Then, you'll write your own program from scratch—using the QuadraticSolver as a model.
   
   Your own program will be a class called ComplexCalc, and will allow users to enter two complex numbers, and then show both the sum and product.
   
   Your program should allow the user to continue as many times as they want, or quit—just like the QuadraticSolver.

Sample Sessions

Here's a sample session from QuadraticSolver

Please enter values for a quadratic equation below.


Please enter a value for a:1
Please enter a value for b:2
Please enter a value for c:-15
Two real roots: 2.0 and -6.0
Do you want to calculate another equation? Y/N
Y
Please enter values for a quadratic equation below.


Please enter a value for a:1
Please enter a value for b:2
Please enter a value for c:15
Complex roots: -1.0 + 3.7416573867739413i and -1.0 + -3.7416573867739413i
Do you want to calculate another equation? Y/N
Y
Please enter values for a quadratic equation below.


Please enter a value for a:1
Please enter a value for b:0
Please enter a value for c:4
Complex roots: -0.0 + 2.0i and -0.0 + -2.0i
Do you want to calculate another equation? Y/N
Y
Please enter values for a quadratic equation below.


Please enter a value for a:0
Please enter a value for b:0
Please enter a value for c:0
Can't calcuate any roots: a is 0, and b is 0
Do you want to calculate another equation? Y/N
Y
Please enter values for a quadratic equation below.


Please enter a value for a:0
Please enter a value for b:1
Please enter a value for c:2
One degenerate root: -2.0
Do you want to calculate another equation? Y/N
N
Goodbye!

      

Please enter values for two complex number c1 and c2, each of the form a + bi



Entering value for c1

Please enter a value for a:a
Sorry, an error occurred: java.lang.NumberFormatException: For input string: "a"
Please try again!


Please enter a value for a:1
Please enter a value for b:2


Entering value for c2


Please enter a value for a:3
Please enter a value for b:4


c1 + c2 = 4.0 + 6.0i
c1 * c2 = -5.0 + 10.0i


Do you want to perform more calculations? Y/N
Y
Please enter values for two complex number c1 and c2, each of the form a + bi



Entering value for c1


Please enter a value for a:0
Please enter a value for b:2


Entering value for c2


Please enter a value for a:0
Please enter a value for b:-2


c1 + c2 = 0.0 + 0.0i
c1 * c2 = 4.0 + 0.0i


Do you want to perform more calculations? Y/N
N
Goodbye!
    

      

Here's one more session from QuadraticSolver that illustrates the error handling that QuadraticSolver has for entering numbers. Your ComplexCalc program should have the same feature. You may reuse code from QuadraticSolver to implement this.

Please enter values for a quadratic equation below.


Please enter a value for a:2
Please enter a value for b:no I don't feel like it
Sorry, an error occurred: java.lang.NumberFormatException: For input string: "no I don't feel like it"
Please try again!

Please enter a value for b:really, I'd prefer not to
Sorry, an error occurred: java.lang.NumberFormatException: For input string: "really, I'd prefer not to"
Please try again!

Please enter a value for b:three
Sorry, an error occurred: java.lang.NumberFormatException: For input string: "three"
Please try again!

Please enter a value for b:3
Please enter a value for c:
Sorry, an error occurred: java.lang.NumberFormatException: empty String
Please try again!

Please enter a value for c:4
Complex roots: -3.0 + 4.795831523312719i and -3.0 + -4.795831523312719i
Do you want to calculate another equation? Y/N
n
Goodbye!

Detailed Instructions

Step 0: Preliminaries

Step 0.1 Copy the starting point files (lab04Proj) from my account

Open a command line prompt in your ~/cs10/lab04 directory, and use the following command. Notice the space and the period at the end of the line—those are very important!

cp -r /cs/faculty/pconrad/public_html/cs10/09S/labs/lab04/lab04Project .

This command will copy a directory containing several Java files, plus all the extra files for a BlueJ project into your directory.

• Note: if you are working from home, you can also use a secure file transfer program (such as scp, sftp, fetch, fugu, filezilla, etc.) to copy this directory onto your PC or Mac. The idea is the same. There are some helpful suggestions offered by your fellow students on the Gauchospace discussion boards about how to do this as well.
  
  

Other ways to access the code:

• For working from home: you can also access this code as a zip file that you can download to your PC or Mac
• For browsing the code online: access http://www.cs.ucsb.edu/~pconrad/cs10/09S/labs/lab04/lab04Project/
• You can also see the Javadoc for the original (unmodified) project

Step 0.2 (Optional, but recommended): Open the starting point files in BlueJ

Open BlueJ, and use the "Open Project" menu item to navigate to the lab04Project inside your ~/cs10/lab04 directory. This will be similar to what you did last week.

Note:

• Although BlueJ, per se, is not required, the use of JUnit is required. So using BlueJ is highly recommended, because it makes using JUnit easy across Linux, Windows and Mac.
• If you choose not to follow this recommendation, you may another IDE such as NetBeans or Eclipse, or you may work at the command line—but in each case, you are on your own for figuring out how to get JUnit working in your personal setup. (Note: all of these setups support JUnit, and getting JUnit working in each of them isn't particularly difficult, but it can be detailed and OS-dependent, so to manage my own time, I'm not going to offer help with that.)

Now the real work begins!

Step 1: Familiarizing yourself with the code.

If you opened up the lab04Project correctly, you'll see In your window, you'll see five Java classes

• QuadraticEqn, a class for a quadratic equation
• Complex, a class for a complex number
• JUnit tests for both of those classes (QuadraticEqnTest and ComplexTest)
• QuadraticSolver, a class with a main() method that presents a user interface to solve Quadratic equations (even if the solutions are Complex)

Please spend some time looking through each of these files—reading them the way you would read a book, from top to bottom. Look at the Javadoc comments for each method, and then read through the method to see how the method is implemented—and indeed, whether the method is implemented yet, or whether it is one you are going to have to implement yourself.

Reading through all of the code rather than just jumping in—will really help you get things done faster in the long run. Plus you will learn more, and be better prepared for the next midterm exam!

Also, learning how to read code is an important skill for programmers—you have to be able to read code, not just write code, because in real-world software development, you are often modifying other people's code. So, here's an opportunity to develop your skill in that area.

Here's the suggested reading order, and what to notice:

• ComplexTest: as you go through this file, notice how the methods of the Complex class work. You may want to have the Complex class open as well, so you can refer to its Javadoc comments as you go through the class.
  • Especially notice the tests of two new methods: add and multiply. Notice that they are static methods that take two Complex parameters, and return a new Complex object. You'll have to implement those methods later, and add some additional tests, so understanding the unit tests is helpful.
  • Also look at the calls to the approxEquals() method in some of the later tests, and notice how it works. Here, you may want to look at the implementation of this method in Complex—this method is complete in the code you were given.
• Complex: you've already perhaps looked at this file a bit as you went through ComplexTest—but now, look at it again, top-to-bottom:
  • This is a modified version of code you've seen before in lab02—but this is an immutable version of Complex (there are no setter methods, or any other mutators).
  • Some methods are stub methods, and some may have hidden bugs for you to find.
  • Read each method carefully, and try to understand how it works, and whether you think it is correct.
• QuadraticEqnTest: as you go through this file, notice how the methods of the QuadraticEqn class work—especially the new ones that solve the quadratic equation with the solution is a Complex number.
  • Just like you did when you went through ComplexTest, you may want to have the QuadraticEqn class open as well, so you can refer to its Javadoc comments as you go through the class.
• QuadraticEqn: just like you did with Complex, read this one top-to-bottom now, looking especially for the stub methods, and any hidden bugs.
  • This is a modified version of some code from lecture.
  • But this version is different: it can find both real and complex roots.
  • Something to ponder: is this version of QuadraticEqn mutable or immutable? You don't have to turn in your answer, but you may want to check with the TA to see if she/he agrees with what you came up with. On the next exam, you'll have to differentiate between mutable and immutable classes, so this is a good opportunity to see if you have that concept down. If you aren't sure, ask your TA for help!
• QuadraticSolver: this is the user interface.
  • Notice how this program concentrates totally on user interface details, and doesn't do any calcuations
  • Notice how the user-interface is broken into small pieces, to keep each method nice and short, and focused on a single task, or small number of tasks.
  • This is yet another example of an important principle of Computer Science called separation of concerns—we keep the user interface separate from the details of calculation. This will allows us to reuse the calcuating parts later for a GUI version of the quadratic solver.
  • Also notice the use of the switch statement in the main method. You'll probably not need a switch statement in the code you write for this lab, but I do want you to be familiar with it, so take a look at how the switch statement works. This is an alternative to using if/else if/else to structure this code.

Step 2: Adding some additional JUnit tests to ComplexTester and QuadraticTester

Note: Look ahead to the grading criteria for this step—so you know how your work will be evaluated. Do this

• before working on this step
• as you work on this step
• when you are finished with this step, before moving on.

Make a habit of this at every step in every lab.

Step 2.1: Complete some unfinished unit tests in ComplexTester.java

In ComplexTester.java. search for the @@@ comments. You'll see two places where you are required to add additional unit tests—one more for the add method, and one more for the mutiply method.

If you've read through the file (as you were invited to) back in Step 1, you've already noticed these, and no doubt already have some idea what needs to be done to create these additional unit tests. You can follow the model of the unit tests that are already there, but choose different values.

Note that one of the whole ideas of test-driven development is to write tests before you write the methods. This forces you to do a hand calculation of an answer (e.g. with pencil and paper, and perhaps a calculator.) This makes you think about the steps involved in computing the answer. This helps you later, when you are writing the code, because you already know all the steps involved.

In a later step, you'll be implementing the add and multiply methods of the Complex class—notice whether writing a test case helps you as you consider how to implement those methods.

Remember, if you modify the code for a given file, to add yourself as an author in the javadoc comment at the top of the file.

From now on, I won't tell you this explicitly—you'll just be expected to know that you are supposed to do it.

Step 2.2: Complete some unfinished unit tests in QuadraticEqnTester.java

In QuadraticEqnTester.java. search for the @@@ comments. You'll see two places where you are required to add additional unit tests—one more for the evaluate method that operates on doubles, and one more for the evaluate method that operates on Complex objects. You can follow the existing unit tests for these functions as a guide.

In a later step, you'll be implementing the evaluate methods—again, notice whether writing a test case first helps you when you get to that step.

Step 3: Implementing the stub methods in Complex and QuadraticEqn, fixing bugs

Step 3.1: Fix the Complex class

Now, look first at Complex, and search for the @@@ comments. You'll see two places where you are required to finish a stub method.

Finish the methods, so that all unit tests for Complex pass (some of the ones for QuadraticEqn may still be failing.)

Note that you can right click on the ComplexTest class and choose "Test All" to run only the unit tests in ComplexTest—that way, you can get a nice green bar, even if you haven't fixed QuadraticEqn yet.

Step 3.2: Fix the QuadraticEqn class

Now, look first at QuadraticEqn, and search for the @@@ comments. You'll see three places where you are required to finish a stub method: the two evaluate functions, and the complexRoot2 method.

Finish the methods, so that all unit tests for the entire project pass.

Step 3.3: Play around with the QuadraticSolver

Before you go on to Step 4, play around with the Quadratic Solver a bit. Run the main method of the QuadraticSolver, and try entering various values for a, b, and c. Getting familiar with this will

• help you in Step 4, where you are implementing a similar program
• help you see how implementing classes and unit tests supports developing "real programs".

Step 4: Implementing your own ComplexCalc class

Now, it is time for you to write a new class from scratch.

• Your class should be called ComplexCalc.
• It should provide a user interface that is functionally equivalent to the sample session for the ComplexCalc program.
• Your program should be broken down into smaller pieces just like QuadraticSolver, to:
  • avoid duplication of code
  • keep each method small, and focused (instead of one huge monolithic main() routine)
• You may use code from QuadraticSolver to get started
  • but beware the dangers of copy/paste.
  • don't leave anything in ComplexCalc that doesn't belong there.
  • There may be deductions if you don't take care of this.
• Be sure that you handle input errors in a robust way
  • See the sample error run from QuadraticSolver

Reminder: look at the grading criteria for this step—before, during and after writing your code.

Turn in Step

This week, use turnin to submit your entire lab04 directory to lab04@cs10

• As promised last week, no detailed instructions. Look back at lab02 or lab03 if you aren't sure how to do this.

Don't be surprised if that ends up being a LOT of files, especially if you are using BlueJ, and don't worry about warnings for binary files.

You are finished—there is no paper component to hand in with this lab.

Grading

Points for this lab are distributed as follows. Partial credit may be awarded for each step at the discretion of the TA/Instructor.

• (10 pts): Correctly executing the turnin step on a directory called lab04
• Step 2.1: adding JUnit tests to ComplexTester
  • (10 pts): changing YOUR NAME HERE in the javadoc comment
  • (40 pts): add the body of two additional unit tests as indicated
  • Note: for this lab, it is not necessary to add javadoc comments for each individual method in ComplexTester and QuadraticEqnTester—the method names are self-documenting. It is necessary, though, to have a javadoc comment for the class as a whole (immediately above the public class ComplexTester line.)
  • (10 pts): remove all @@@ comments
• Step 2.2: adding JUnit tests to QuadraticEqnTester
  • (10 pts): adding your name as an additional author in the javadoc comment (there is no @@@—you just need to do this.)
  • (40 pts): add the body of two additional unit test as indicated.
  • (10 pts): remove all @@@ comments
• Step 3.1: implementing stub methods in Complex
  • (10 pts): adding your name as an additional author in the javadoc comment (there is no @@@—you just need to do this.)
  • (20 pts): correctly implement the add method
  • (20 pts): correctly implement the multiply method
  • (10 pts): remove all @@@ comments
• Step 3.2: implementing stub methods in QuadraticEqn
  • (10 pts): adding your name as an additional author in the javadoc comment (there is no @@@—you just need to do this.)
  • (20 pts): correctly implement the evaluate method for doubles
  • (30 pts): correctly implement the evaluate method for Complex
  • (30 pts): correctly implement the complexRoot2 method
  • (10 pts): remove all @@@ comments
• Step 4: ComplexCalc
  
  • (10 pts): creating a ComplexCalc.java
  • (20 pts): if you work by copying/pasting, removing all comments/methods/variables that are specific to QuadraticSolver, and do not apply to ComplexCalc
    • deductions of 5-10 points may be made for each comment or method that is left behind that doesn't belong in ComplexCalc, up to a maximum of 30 points.
  • (40 pts): correctly implementing a program that provides the user interface and functionality shown in the example (see the Overview section)
  • (20 pts): good program structure/style:
    • is the program broken down into smaller units (as in the QuadraticSolver example—which is good), or is it all one big monolithic main method (bad)
    • are variable names, parameter names, method names, etc. chosen in a way that makes the program clear (good), or are they arbitary, or copied/pasted
  • (20 pts): Javadoc comments are present for all methods, have good explanations of the methods, and @param and @return items are there when appropriate, not there when they should not be.
    • Note that even though Javadoc is not generated for private methods—you should still write Javadoc comments for the private methods of ComplexCalc for practice, and because in a future exercise we may factor those out into a separate class as public methods.

Total points: ?

Due Date: You should do your best to complete as much of this lab as possible within the assigned lab time 05/07 or 05/08. If you don't, you may continue to work on it over the weekend, and early next week. We'll accept this assignment up without penalty up until noon Thursday on 05/14.

Submissions turned in after that time are subject to receiving zero credit—they will be graded only they arrive before the TA finishes work on grading the entire "batch" of assignments submitted.

After you turnin: An extra credit opportunity—maybe

Can you find any bugs? I'm not aware of any—that is, it is my belief (my hope, actually) that if you follow all the instructions above—you've implemented the methods indicated, and all the existing unit tests pass, along with your new ones—then, in that case the QuadraticSolver won't return any wrong answers, regardless of what you input.

However, if you can find a bug in the underlying Complex or QuadraticEqn classes, then there is an extra credit opportunity:

• Find the bug
• Add a unit test that doesn't pass becuase the bug is present
• Fix the bug

Similarly, if you find a bug—a genuine bug (see below)—in the user interface code in QuadraticSolver, then explain the bug in a comment flagged with // BUG-FIX, fix it, and submit your fix.

If you do this, put the special comment // BUG-FIX in your code in the unit test that exposes the bug, and next to the lines of code that fix the bug.

The amount of extra credit given will range from 0 pts to 100 pts, depending on the severity of the bug, and your skill in presenting your solution.

Note again: there may not be any opportunity here. My code might be free of bugs.

Also note that formatting glitches, ease of use issues, or differing mathematical interpretations of what consitutes a "degenerate root" don't count here as bugs. I'm talking about a genuine wrong answer—that's the threshold here.

If you find a bug after you do the turnin step, you may do a second or third turnin. If you do this, please email the TA for this assignment to let him/her know you did that.

End of lab04