Lab 1: CoinStrip

In this lab, will write a program to play the Silver Dollar Game found at the end of Bailey Chapter 3 (page 67). In addition to gaining experience writing, compiling, and running programs from scratch, this lab will help us to think about how we can efficiently represent data and break our logic into reusable methods. Careful planning will help tremendously, so take the time to write a well-thought-out design document before arriving to lab.

PRE-LAB: Design Documents

Read through this lab handout and sketch out a design for your Silver Dollar Game program. You should use the sample Nim Design Document as a guide. Each week your design document will account for a small portion of your lab grade, so please bring it to lab, be prepared to discuss it with a partner, and be prepared to submit it. For the first lab, it is OK if the design is rough: we are not going to deduct points for correctness. The purpose is to ensure that you think about the lab in advance.

Step 0: Clone your repository

First, you want to pull the starter code onto your local machine. First, navigate to your /136 folder (or whatever folder you’re using to store your local lab work) using the cd command. Then, run

   $ git clone https://evolene.cs.williams.edu/cs136-labs/<YOUR-USERNAME-HERE>/lab01-coinstrip.git

If you run cd coinstrip and then ls you will see that we’ve given you some starter code to help you start writing your program.

Step 1: Hello Odd World: Writing Your First Program.

In this step, we will write, compile, and run a Java program under Unix that prints the first ten odd numbers using a for loop. You don’t need to make a design document for this part of the lab; just the main coinstrip part.

We will create a new file called Odd.java. You will turn in your source code for Odd.java by committing it to your local git repository and pushing that commit to your private repository on GitLab. You should complete this step by the end of lab on Wednesday.

The instructors and TAs are around to give as much assistance as we can on this step, so do not hesitate to ask questions! We want you to successfully complete this step so that you can move on to the main lab assignment. This is the simplest program we will write all semester, but it is often the hardest to complete. Ask questions early and often!

Inside your project folder, create a new file using Atom named Odd.java. That file should contain a class called Odd, and that class should include a method called main.
Once you have written your program, compile it using
```
 $ javac Odd.java
```
After successfully compiling your program, you should see a new file called Odd.class when you type
```
 $ ls
```
To test your code, type
```
 $ java Odd
```

The output should look something like:

When you have finished writing Odd.java and are happy with the output, please commit Odd.java (with a meaningful commit message) and push it to your private repository. Confirm that your changes are visible online by visiting your GitLab repository in your web browser.

Step 2: Main Lab Program (CoinStrip.java)

This week, we will write the Silver Dollar Game at the end of Bailey Chapter 3 (page 67). As you think about the design of your game, you should first decide on a representation of the coin strip.

Make sure your representation supports all of the operations necessary such as:

Generating different game boards. Your game boards must conform to the following rules:
- Each game board must have at least three coins, but the exact number of coins on a given game board must be chosen with some randomness.
- The locations of coins must be randomly selected. In other words, over the course of playing several games, I should expect to encounter different starting configurations.
- No game should be “won” before it starts. In other words, there must be at least one legal move.
Testing whether a move is legal. The rules are fully described in the textbook, but here is a summary:
- No “going right”: Coins can only move to the left.
- No “double occupancy”: At most one coin can occupy a space at a given time.
- No “jumps”: Coins cannot pass another coin.
- “Mandatory progress”: A coin must move one or more spaces.
Printing the board. Your game board’s appearance should make it clear to the players exactly what the state of the game is at any given time. It should also provide enough information to the player that they can specify the move that they would like to make next. However, you have some flexibility to add your own “style” to how you display the board. Simple is fine. Elaborate is fine. Just make it clear!
Testing for a win: That is, is the game over?
Moving pieces. When a legal move is given, you should be able to adjust the state of the game to reflect that move. This includes things like relocating coins, changing the current player, etc.

When we say “representation,” what we mean is: what data structures will you use? For instance, you might use an array of bool variables—or perhaps an array of variables of type int. Once you have chosen a representation, write down the set of operations supported by your data structure. Think about what parameters they take, what values they return, and what the methods do. In lab, we will briefly discuss this initial design with a partner. Bring a printed copy of your design to lab for discussion! We will check design documents at the beginning of lab.

A good exercise to do when designing a representation is to consider alternative designs. For example, do you want a data structure that stores the spaces on the game board? Or would it be better to use a data structure that stores the coins themselves? Often it helps to think about the trade-offs: which operations become easier to implement if you choose one representation over another? Expert computer scientists almost always do this step out on paper before they start coding, which is why we want you to work on a design document before you start.

The main method of your CoinStrip class should set up the board and then prompt each of two players to make their moves. A move will be of the form:

<cn> <ns>

where <cn> specifies the coin to be moved and <ns> specifies the number of spaces that coin should be moved.

The program should prompt the user for another input if the move is illegal.

To read input from a terminal window, you should use the Scanner class, as we have seen in lecture. Consult the scanner handout, Oracle Scanner documentation or sample code from class for details.

To help you get started, we have given you starter code with some method stubs (i.e. the name and parameters of some example methods, without the body of the methods filled in). These are completely optional! Feel free to use these methods, change them to be more useful in your code, or not use them at all.

Step 3: Style

Part of being a relatively new programmer involves developing an understanding of what it means to have “good style”. This is made difficult by the fact that “good style” is both hard to quantify, and hard to agree upon.

To help us all along our lifelong quests to write better code, we have included a tool inside each of our repositories that checks our code against some industry-standard, agreed-upon best practices. This tool is called checkstyle.

In this first lab, we have configured checkstyle to give warnings for most classes of stylistic “mistakes” that we might make. We encourage you to review these warnings and follow the suggestions to improve your code.

However, we have also configured one checkstyle rule to output an error. You must fix all checkstyle errors. Your program will be graded on both correctness and style, and we will use checkstyle errors as our measure of your program’s style.

checkstyle will report an error if your program:

declares a class variable but does not specify the variable’s visibility. All class variables must be declared as public, private, or protected. If you do not specify a class variable’s visibility, the variable is given “default” visibility, which is very likely not what you want.

It’s OK if you’re not sure about this error—we’ll be talking more about visibility over the coming week. If all of your variables are local variables (declared within methods), then this error will not appear.

As the semester progresses, we will convert more and more style checks from warnings to errors. It is in your best interest to fix all warnings—both to develop better coding practices, and to prepare yourself for future labs.

To run checkstyle, you would type the following command at the terminal:

    ./checkstyle

The ./ is a Unix thing: it tells the terminal where to look for the checkstyle program. The . (dot) tells Unix to look in the current directory. This will run checkstyle on every Java program in your directory. To run checkstyle on just one Java file, you would instead specify:

    ./checkstyle SomeFile.java

checkstyle is a new addition to the course this Spring, based on student feedback. We hope it helps! If you have any questions about checkstyle output, please ask an instructor or a TA for guidance.

Lab Deliverables

When you are finished with your CoinStrip program, commit and push your lab files. Your repository should have the files:

cs136lab1-USERNAME/
           checkstyle
           Odd.java
           CoinStrip.java
           README.md

Submitting Your Lab

As you complete various milestones, you should commit your changes and push them. Commit early and often. When the deadline arrives, we will retrieve the latest version of your code. If you are confident that you are done, please include “Lab 1 Submission” as the commit message for your final commit. If you later decide that you have more edits to make, it is OK. We will look at the latest commit before the deadline.

Be sure to push your changes to GitLab
Verify your changes on GitLab. Navigate in your web browser to your private repository on GitLab. It should be available at https://evolene.cs.williams.edu/cs136-labs/<YOUR-USERNAME-HERE>/lab00-environment.git
You should see all changes reflected in the various files that you submit. If not, go back and make sure you committed and pushed.

We will know that the files are yours because they are in your git repository. Do not include identifying information in the code that you submit! Our goal is to grade the programs anonymously to avoid any bias. However, in your README.md file, please cite any sources of inspiration or collaboration (e.g., conversations with classmates). We take the honor code very seriously, and so should you. Please include the statement “I am the sole author of the work in this repository.” in the comments at the top of your Java files.