ITEC 120 2007spring ibarland, jpittges

home—info—exams—lectures—labs—hws
Recipe—Laws—lies—syntax—java.lang docs—java.util docs

lab01b
lab01b

Discussion: Commenting code

Alas, just getting a function to run isn't enough. Why not? Well, consider coming across the following code (which does run):

  double f( double r ) {
    return 3.14 * r * r * r / 3;
    }

The Zeroth Law of Programming
Code is meant to be read by humans.

(For example: One very easy mistake to make with functions we've written, is remembering that pizzaArea should be passed the pizza's diameter, not the radius. There is no way for the computer to help us remember this.)

We'll come back later to what comprises an adequate description. Note that just the fact of choosing a good “self-documenting” name goes a long way; avoid generic names like f or calculate. But, just because a name seems self-documenting to you doesn't necessarily mean that further comments aren't needed. For example,

     double rightConeSurfaceArea( double r )

Comments, and Javadoc

Okay, back to our pizzaArea example, Attempt 3, where we add a description. Descriptions precede the function, and are enclosed by /* and */.

  /** Calculate the area of a pizza, given its diameter.
   * @param diam The diameter (in inches); must be non-negative.
   * @return the surface area of the pizza top (in square inches).
   *         Accurate to within 1%.
   *   pizzaArea(16) ~= 200.96
   *   pizzaArea(12) ~= 113.04
   *   pizzaArea(20) ~= 314.0
   *   pizzaArea( 0) ~=   0.0
   *   pizzaArea( 2) ~=   3.14
   */
  double pizzaArea( double diam ) {
    return 3.14 * (diam/2) * (diam/2);
    // Single-line comments can also start with '//',
    // and they last until the end of that line.
    }


  /* You can have comments which begin with '/*',
   * instead of '/**'.  These are just regular multi-line comments, 
   * and are not used to generate java documentation.
   */

  /* By the way,
     you don't need that row of stars down the
     left side; that's just to improve readability.
   */

• The javadoc comment begins with /**, which is one more asterisk than normal comments use.
• The javadoc comment is placed immediately before the function it's describing.
• The first line is a brief summary of the what the function does (which is different from how it does it!)
• The next line tells people what the parameter means: @param followed by the paramter-name followed by a brief description.
• The next line tells people what the function returns; it starts with the special word @param. (Sometimes this is identical to the first javadoc line.)
• With the @return line is an appropriate place to list your test cases.

There is a bonus to writing this information using those tags @param and @return: In BlueJ, look at the code window, and in the upper-right corner change Implementation to instead ask for the Interface view. Voila! Other programmers can look at this web page for pizzaServer, and know how to call our functions, without ever actually having to look at our code!

home—info—exams—lectures—labs—hws
Recipe—Laws—lies—syntax—java.lang docs—java.util docs

Writing a method

For today's lab, you must work with a partner. We will check off your work, before leaving.

In yesterday's lecture, we saw that one function (like friPizzaArea) might call another function (like pizzaArea).

• Create a new project for today, lab01b.
• Make a class PizzaServer (again), and copy/paste in the above code for pizzaArea.
  We will add a method within the same class which contains pizzaArea -- not make a whole new stand-alone class. More precisely: we are adding new possible behaviors to PizzaServers!

• Some customers are concerned with the surface area of their pizza. Others ignore the crusts, and want to ask the server how much topping-area each pizza comes with. The server happens to know that Krusteaze Pizzas have a 3″ border of crust all the way around them (what cheapskates!).

  Write the function toppingArea.

  • Step 1: What are some test cases?
    You'll probably want to draw some pictures. (What is the smallest diameter which even makes sense, for this problem?) Feel free to call pizzaArea, to figure out the exact numbers.
  • Step 2 (new): Write the javadoc for your function. You can include the test-cases here.
  • Step 3: Write the code.
    • What is the signature of toppingArea — the first line of the function, which gives the return-type, name, parameter-type, and parameter-name?
    • The function itself will include “return” followed by some arithmetic (that's the next step) followed by a semicolon.
    • Now: what is the arithmetic, to compute the topping area, given the 3″ crust? Think back on how you worked out the test cases, earlier.
  • Step 4: Compile your program, and run the test cases. Do you get the answers you expected?

• Raise your hand, and the instructor or peer instructor will come around to check off your work. For full points, make sure you don't have any repeated code — multiplying by 3.14, and squaring a radius, should only happen once in your entire program, up in pizzaArea, and nowhere else.
  (In my solution, the only arithmetic inside toppingArea is a single subtraction … and one multiplication(?!).)
• Make sure you and your partner both have a copy of the code, for future reference.

• One last problem (not needed for check-off, but you should be able to work through it):
  Some people actually like the crust of a pizza! They want to ask PizzaServers how much crust there is, on a pizza of a given size!

  Follow the same steps above, to write crustArea. (In my solution, the only arithmetic inside crustArea is a single subtraction.)

home—info—exams—lectures—labs—hws
Recipe—Laws—lies—syntax—java.lang docs—java.util docs

©2007, Ian Barland, Radford University Last modified 2007.Aug.27 (Mon)

Please mail any suggestions (incl. typos, broken links) to iba�rlandrad�ford.edu