Lab 1: Unix, Workflow, and CoinStrip

In this lab, we will explore tools, techniques, and workflows used by many programmers. We will adopt some of these best practices and use them for managing our written and lab assignments, collaborating, and exchanging feedback.

The skills developed in this lab will help us on multiple fronts. The tools that we explore (Terminal.app, the Atom text editor) and the workflow we use (checkpointing our progress using the git version control system) will help us to work efficiently, safely, and flexibly throughout the semester.

We will also 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 Step 0: Version Control Systems and GitHub

Please complete PRE-LAB Step 0 by Monday at 4pm. This part is worth 2 basis points of your Lab 1 grade.

Review what a version control system is and why you might want to use one. We will talk about these more in the lecture and the lab.
Sign up for a GitHub account by following the GitHub Getting Started guide on the course webpage. Please choose your username thoughtfully–students often use a GitHub account for years and like to show their work to prospective employers!
Complete the Hello World guide. We will be using the features discussed throughout the semester.
After you’ve registered, please fill out this Google Form, and be sure to include your GitHub username. This form is how we know that you completed PRE-LAB Step 0.

PRE-LAB Step 1: Testing Your CS Mac Lab Account

Login to a MacOS machine in TCL 216 or TCL 217. You must use your CS-department username and password. Please see Mary Bailey in TCL 312 if you do not have a CS-department Mac account or if you have forgotten your username/password.

PRE-LAB Step 2: Design Documents

Read through this lab handout and sketch out a design for your Silver Dollar Game program. You should use the sample Dice 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 week, 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 1: The Mac Lab Environment

Complete the following Unix tutorial. That guide will teach you how to log in and out of the machines, access the command line shell, use basic Unix commands, and compile and run Java programs. Depending on your prior background, you may already be familiar with this environment. If that is the case, please refresh your memory and review the following commands:

  ls         cd         cp         mv         rm         mkdir      pwd
  man        history    cat        more       grep       head       tail    	

To be successful, you should know how to use each command on the command line and use them to explore, create, modify, and rename files. Even though there is nothing to turn in for this step, learning core Unix commands is going to help you with everything you do this semester and beyond.

Step 2: Cloning

By the start of lab, you should have a private repository in your GitHub account, named cs136_lab1_USERNAME, where USERNAME is replaced with your GitHub ID. Clone the repository to your local disk using the following steps:

In your web browser, click the green “clone or download” button on the right side of the repository page, above the list of repository contents. You can clone via HTTPS or SSH. We’ll use HTTPS, so first click on the “Clone with HTTPS” link and then click on the little clipboard with an arrow icon to copy the URL to the local clipboard.
Open up the Terminal.app application and navigate to your home directory by typing
```
 $ cd ~
```
Make a new directory called cs136 using
```
 $ mkdir cs136
```
Change directory into the cs136 directory using
```
 $ cd cs136
```
Now clone your private repository cs136_lab1_USERNAME by typing git clone and then pasting the copied repository URL on the command line (⌘-v). It should look like this:
```
 $ git clone https://github.com/williams-cs/cs136_lab1_USERNAME.git
```
You will be prompted for your username, and then for your password. Enter them in when prompted.
Change directory into the new repository directory using
```
 $ cd cs136_lab1_USERNAME
```

Step 3: Text Editors

There are many good text editors. Traditionally, we have used the Emacs text editor in CSCI 136. Emacs is a very powerful editor, and being proficient in Emacs is worth the time investment and the steep learning curve. However, this semester we will start by using the Atom text editor, and revisit Emacs after Spring break.

Open your cs136lab1-USERNAME project folder in Atom:
- Using the launcher, search for and open the Atom application.
- Once you have opened Atom, go to the File menu, click on Add Project Folder, and select the cs136lab1-USERNAME folder that you just cloned.
- In the left pane, you will see a list of all of the files in your project. Click on the README.md file.
Open the README.md in your repository. You may be surprised by the way README.md looks in Atom compared to how it looked on GitHub. This is because GitHub understands and formats “Markdown”, just like a Web Browser understands and formats HTML. You may want to use the GitHub markdown syntax to format your file so that it displays nicely on github.com.
The README.md of a repository is shown when you view that repository on github.com. Make a small change (perhaps write the word “test” at the bottom of the page). You should see that the README.md file’s tab at the top of the application now has a little blue dot. That dot means the tab has unsaved changes. Save the file. The dot should disappear.
You should now see the README.md file change colors in the left-hand menu. If a file is yellow, that means that you have made changes to that file since you last committed it to your git repository. (If a file is green, then git does not yet know that the file exists.)
Go to the Atom menu labeled “Packages”, then scroll to the “GitHub” entry, then click the “Toggle Git Tab” entry. You should now see a new column on the right side of Atom.
In the “Unstaged Changes” section on the right, your yellow README.md file should appear. If you click on the “Stage All” button, it should move that file (and all other files with pending changes) to the “Staged Changes” section. Once this is done, you can write a message in the window labeled “Commit Message” and press the commit button. (Your message should usually be something informative to describe the changes that were made. In this case, you can just write “Test”).
You should now see a small change to the bottom right corner of the Git tab. There should be two arrows, one pointing down and the other pointing up. Next to the arrow that is pointing up, you should see the number one in parentheses (1). This means that you have a commit on your machine that is not yet sync-ed with your repository on github.com. Go ahead and click that button and then press “Push”. It will ask you for your password. If you are successful, you should see your changes reflected in your repository on github.com. Congratulations on making your first git push.

Step 4: 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.

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 GitHub. 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 GitHub repository in your web browser.

Step 5: 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
testing for a legal move
printing the board
testing for a win
moving pieces easily
…

When we say “representation,” what we mean is: what data structures will you use? For instance, you might use an array.

Once you have chosen a representation, write down the set of operations supported by your data structure. Since we’re using Java, your representation should be hidden inside a class called CoinStrip. Operations are made possible by providing public methods that implement those operations. Therefore, you should specify the public methods of your CoinStrip class. 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.

If you’re feeling frisky, you may read ahead to the book’s section on Vectors, but the lab can be implemented just as well with arrays.

The main method of your CoinStrip class should create a CoinStrip object 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.

Step 6: Thought Questions

Consider the following questions as you complete the lab:

How might one pick game sizes so that, say, one has a 50 percent chance of a game with three coins, a 25 percent chance of a game with four coins, a 12 1/2 percent chance of a game with five coins, and so on? Would your technique bias your choice of underlying data structure?
How might one generate games that are not immediate wins? Suppose you wanted to be guaranteed a game with the possibility of n moves.
Suppose the computer could occasionally provide good hints. What opportunities appear easy to recognize?
How might you write a method, computerPlay, where the computer plays to win?
A similar game, called Welter’s Game (after C. P. Welter, who analyzed the game), allows the coins to pass each other. Would this modification of the rules change your implementation significantly?

Hint: When flipped, the Belgian Euro is heads 149 times out of 250.

Step 7: Style

As relatively new programmers, we are all developing our 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.

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, answer the thought questions at the end of the lab, and put your answers in a separate file called PROBLEMS.md. Commit and push PROBLEMS.md along with your other lab files as part of your repository. Your repository should have the files:

cs136lab1-USERNAME/
           checkstyle
           Odd.java
           CoinStrip.java
           README.md
           PROBLEMS.md
           MISTAKES.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 GitHub
Verify your changes on Github. Navigate in your web browser to your private repository on GitHub. It should be available at https://github.com/williams-cs/cs136lab01_coinstrip-USERNAME 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.

Bonus: Mistakes

Did you find any mistakes in this write-up? If so, add a file called MISTAKES.md to your GitHub repository and describe the mistakes using bullets. For example, you might write

* Where it says "bypass the auxiliary sensor" you should have written "bypass the primary sensor".
* You spelled "college" wrong ("collej").
* A quadrilateral has four edges, not "too many to count" as you state.

For non-trivial corrections, you will receive 1 bonus point on this assignment for each mistake we are able to validate. Bonus points cannot bring your score above 100%.