Lab 2: 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.

A key idea in software engineering is that careful planning helps tremendously. Just as a construction crew should not build a house without blueprints, programmers should not write programs without a design document. Therefore, in the first part of this lab (week 1), we focus on writing a design document. In the second part (week 2), we use our design document to write code.

To give yourself plenty of time, you can (and probably should) proceed with the second part of this lab as soon as you have written and submitted your design document. You do not need to wait until the second week to start programming!

Part 1: Design Document

Step 1: Clone your repository

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

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

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

Step 2: Write your design document

Read through this lab handout and produce a design for your Silver Dollar Game program. Refer to the Design Document Guidelines to help you. If you want to see an example for a similar program, take a look at the Design Document for Nim. Your starter repository comes with a design document template in a folder called design_doc_templates. This folder contains templates in a variety of formats:

design_document.docx is a Microsoft Word document.
design_document.rtf is a Rich Text document.
design_document.txt is a plain text file. Choose whichever one you prefer.

Plan on working on this design document with your lab partner. Each of you should produce your own document, but you may discuss and jointly develop ideas.

Step 3: Submit your design document

When you are done, do the following.

Save your design document as a PDF. On most computers, you can produce a PDF by going to to the File menu, selecting Print and then selecting the option to print as a PDF. Note that Visual Studio Code does not have the ability to print, but many other file editing programs can (e.g., Microsoft Word, Notepad.exe, TextEdit and so on).
Go to the CSCI 136 Lab 2 Design Document Turn-in Form and send us your design document.
Be sure to add the file to your git repository so that you also store a copy with your code.

We will review your design document and provide written feedback to help you with part 2. Do not wait to receive feedback before proceeding with part 2; you should use whatever time you have to work on your implementation.

It is OK to change your design document once you start coding. The purpose of a design document is to help you identify “next steps.” Nevertheless, sometimes you encounter unanticipated details as you code. When this occurs, go back and update your design. A design document is a living document, so it is always OK to edit it. If you update your design after you submit it to us, you do not need to send it using the form. Just be sure that you’ve added it to your git repository.

Part 2: Implementing Your Design

Step 1: Main Lab Program (CoinStrip.java)

This week, we will write the Silver Dollar Game at the end of Bailey Chapter 3 (page 67). By this point, you should have decided on a representation of the coin strip. When we say “representation,” what we mean is: what data structures will you use? For instance, you might use a bool[] or perhaps an int[] to store information about the coin strip.

As you implement, be sure that your representation supports all of the necessary operations:

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, one 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: 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.
Finally, your program should never crash. To do this, you will need to anticipate the kinds of errors a user might make as they input a move.

The main method of your CoinStrip class should set up the board and then prompt each of two players to make their moves. A player will enter a move with input 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. For example, my program might ask something like:

Enter move:

and I might enter the input:

Enter move: 3 2

meaning that I’d like to move coin 3 two spaces to the left. 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. As stated above, you should appropriately handle input errors. When using Scanner, there are two approaches. You may decide which approach you prefer:

Use Scanner’s hasNext... family of functions to check to see whether the input is of the right type. If it isn’t, “flush” the input using next, tell the player that they made a mistake, and prompt them again.
Use an exception handler with try … catch. After catching the error, “flush” the input using next, tell the player that they made a mistake, and prompt them again.

All we have given you for this lab are a TwoPlayerGame.java file and an empty CoinStrip.java file. The latter states that it implements the TwoPlayerGame interface, but looking at it, it clearly does not yet. A good place to start is to copy those methods over and to provide just enough implementation so that javac compiles without producing compilation errors. For example, the following method declaration is in TwoPlayerGame

public boolean isGameOver();

and if we copy it over to our CoinStrip class, we might add the following very simple implementation:

public boolean isGameOver() {
  return false;
}

The above is clearly not what we ultimately want (because if it were, the game would never finish), but it does let us run javac without producing a compilation warning for that one method. If you repeat this process for all of the methods, and running javac produces no errors, then you know that your code contains all of the methods required by the TwoPlayerGame interface.

Step 2: 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:

lab02-coinstrip/
    CoinStrip.java
    TwoPlayerGame.java
    design_document.[docx/rtf/txt]

We do not need your .class files, as we will compile your code ourselves. Be sure that your code compiles before you submit it!

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 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>/lab02-coinstrip.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.