COMP 2100 Lab Exercise 1: Warm-up Nim exercise
(15 points + possible 2 point bonus)
Turn in before the next lab period.

1. The folders and files you need to complete this exercise are in Ex1.zip. Right click on the link to download, then unzip into the Z drive folder you've created for this assignment. This will create a folder called Ex1 containing five files and one subfolder. The files are GameManager.java, Player.java, NimUI.java, NimGame.java, and Pile.class. The folder is OOJ, which contains some utility classes used by the application.
2. Notice that Pile.java is not provided but Pile.class is! This allows you to run a completed application in advance to see how it should work.
3. The application class is NimGame. Compile in jGRASP and run to play the game a few times to get used to it.
4. You will next implement the Pile class based on its API specification. Start by selecting New->Java from the jGRASP File menu. Type in a class definition, along with the appropriate instance variables and methods. Note that the first successful compilation will replace the original Pile.class file so you may want to first save a copy of it in a different folder or under a different name.
5. Once you have Pile at least partially implemented and in compilable form, compile it then test it. When you are satisfied with the results, go ahead and run NimGame again to assure yourself that it works correctly.

Reading the Pile specification, you'll notice that all the methods contain either a "Precondition:" expression, a "Postcondition:" expression, or both. The precondition expression is a condition that the method expects to be true at the time that method is called. The postcondition expression is a Boolean condition that the method guarantees to be true when the method is finished, assuming the precondition is met. Preconditions and postconditions are foundations for programming by contract.

When testing your Pile methods, be sure to try them with argument values that do not meet the precondition. What is the result?

Do your best to comment your code with Javadoc-style comments that attempt to match the comments on the Pile class API. To preview a javadoc-produced page in jGRASP, click the open-book icon located left of the compile icon. "Precondition" and "Postcondition" are not Javadoc tags but you can format them by marking them up with standard HTML tags - this is left as a bonus.

Just-Enough-Javadoc

Javadoc is a utility included with the Java compiler that produces API documentation based on specially-formatted comments in Java source code files. When you read Java library documentation such as the Java 2 Standard Edition 7 API Specification, you are reading HTML documents (web pages) produced by Javadoc.

Javadoc comments are placed above the component they describe. Comments describing a class are placed just above the start of the class definition. Comments describing a method are placed just above the method definition.

A Javadoc-style comment starts with "/**" on a line by itself and ends with "*/" on a line by itself. The comments placed between them represent descriptions and tags.

Example Javadoc tags:
@param is used to describe one parameter of a method
@return is used to describe the return value of a non-void method

Example method with Javadoc-style comments

/**
 *  Method to return the greater of two integer values.
 *  @param first an integer value
 *  @param second another integer value
 *  @return The greater of the two parameter values
 */
 public int greater ( int first, int second ) {
    return  (first > second) ? first : second ;
 }

public int greater(int first,
                   int second)

As stated above, Javadoc does not define tags for Precondition and Postcondition! One way to include them is to format them using HTML within the Javadoc comment. Javadoc will pass any HTML code through without modification. This is left as a bonus.

Just-Enough-HTML

You don't need many different tags to produce Javadoc-style formatting. These should be enough to get you started:

Tag	What it does
<em> </em>	Render enclosed text in italics
<strong> </strong>	Render enclosed text in bold
<p> </p>	Render enclosed text as a new paragraph
<tt> </tt>	Render enclosed text in a constant width font
<br>	Insert a line break at this point

Another approach is to study the HTML source produced by Javadoc for the param and return tags and reproduce it. Those HTML tags will differ from the ones shown here. There is more than one way to mark up text to achieve a given visual result.

Scoring

To Turn In