Assignment

Summary

Write Java code to determine the state of a tic-tac-toe board and write tests that validate the correctness of your code. We will provide the interface for your code, but the design of the implementation is up to you. Try to design and write your code to be as clean and readable as possible.

Background

Tic-tac-toe (https://en.wikipedia.org/wiki/Tic-tac-toe) is a paper-and-pencil game for two players, X and O, who take turns marking the spaces in a 3x3 grid with their mark. Player X is the first to make a mark. Once a space has been marked, it cannot be marked again. The player who succeeds in placing three of their marks in a horizontal, vertical, or diagonal row wins the game, and the game is over (i.e., no further actions occur).

Specification

The provided TicTacToeBoard class interface has a constructor that expects a description of the state of a tic-tac-toe board in the form of a Java String. This String should consist of 9 characters, one for each position of the board. The characters are ordered in groups of three characters (left-to-right) specifying top, middle, and then bottom horizontals, as shown in Figure 1. The String is case-insensitive. Squares marked by player X are specified with an ‘x’ or ‘X’ and squares marked by player O are specified with an ‘o’ or ‘O’. Any other character is considered to be an empty square. Figure 2 shows what a board specified as “o-XxxoO.z” would look like.

                   0 | 1 | 2
                   ---------
 "012345678"  ->   3 | 4 | 5
                   ---------
                   6 | 7 | 8

Figure 1. The mapping from Strings to positions in the Tic Tac Toe board.

 O |   | X
 ---------
 X | X | O
 ---------
 O |   |

Figure 2. The above Tic Tac Toe board could be described as: o-XxxoO.z

Your implementation of evaluate should analyze the state of the specified board and return one of four Evaluation values. The values are defined as a Java enum type in Evaluation.java. If you aren’t familiar with enums in Java, there are a lot of good references on the Internet; it isn’t that difficult of a concept.

If the argument describes a board state, but one that is not reachable by playing a game of tic-tac-toe, then your code should return UnreachableState. If the function’s argument describes a valid, reachable board state, then it should return Xwins, Owins, or NoWinner if the board is in a state where X has won, where O has won, or where no one has won, respectively.

If the argument passed in the constructor doesn’t correctly describe a board, you should throw an IllegalArgumentException.

Your repository

Use the following link to create your own copy of the TicTacToe repository on GitHub:

https://classroom.github.com/a/DpSFSOJ7

In IntelliJ, create a new project using the following menu command:

File -> New -> Project From Version Control -> GitHub

A dialog should pop up. Select the appropriate repo from the list labeled “Git Repository URL”. Click the “clone” button. Since the version of Java you are using might be different than the one I used to create the project, you might need change the Project SDK using the menu command below. Select a Project SDK that you have installed that is Java 1.8 or greater. For some of you a pop-up might appear asking you to choose a different Project SDK. Regardless, the update your file structure navigate to:

File -> Project Structure

To commit your work, use the following command. Write a useful commit message, and be sure to push your work to GitHub.

VCS -> Commit

Be sure to frequently commit your changes. When writing code, you should break your work into lots of little pieces (15-60 minutes of effort). Your work cycle should be to: 1) pick the next piece that you can implement, 2) implement it, 3) debug it until you are confident that it works, and 4) commit and push it. That way, if anything happens, you never lose more than a small amount of work. Part of your grade on code review assignments will be based on progressively committing your code. Note: if your code is broken and not compiling, you probably want to get it working before committing.

Flexibility

You should design your code in a way that is extensible to different board sizes. In other words, try to minimize the amount of code that would need to be changed if we wanted to evaluate $n \times n$ boards for some $n$ other than 3.

Testing

The primary motivation for this assignment is to give you a moderately complicated function for which to write black box tests. Following a test-first philosophy, we’re going to ask you to write your tests before writing your code. More precisely, you should have tests checked in to the repository before you have code.

Your tests should be implemented in the provided TicTacToeTest class using Junit4. Each assert should be in a separate test. Name your tests with meaningful names. For most tests, no comments are necessary, because the name of the test is sufficiently explanatory. Write enough tests to give yourself confidence that your implementation will be correct if it passes all of the tests. Exhaustive testing is untenable, as each of the nine positions of the board can be X, O, or blank, leading to 3⁹ (over 19,000) board configurations.

While testing is a key concept in this course and we expect tests where possible in all assignments, in this particular assignment it is the focus. This means that in this assignment, we consider your tests to be the same as your code. That is, you should not share them with each other before code review.

Design and Style

We are using the Google Java Style Guide for the Java code that we write in CS 126. For this assignment, the most important sections to read are for Formatting, Naming, and Javadoc (see the URL below). However, you should at least skim through the entire style guide to get a good grasp of other style conventions for later assignments.

You should follow the style guide as closely as possible to write readable, professional-looking code. Remember - you are writing code not just for yourself, but for others!

https://google.github.io/styleguide/javaguide.html

Submitting the assignment

After pushing your code to GitHub, you will need to submit your code to Gradescope. Please see the course info page for signing up for Gradescope.

Remember that committing your code is different from pushing your code. Committing your code saves the changes you made, and ideally you will be committing frequently based on small units of progress (e.g. implementing a function). However, those commits will only be on your local computer and not on GitHub until you push them - then, the changes you made on your local computer will show up in GitHub.

To actually submit the code to be graded, you must submit to Gradescope after pushing to GitHub. Double check that the code submitted to Gradescope is the code you actually want to submit - even if you make changes on your computer, they won't show up in Gradescope if you didn't commit and push to GitHub first.

Assignment Rubric

Note that this rubric is not a comprehensive checklist; it’d be impossible to list out every single thing that you should be considering while writing your code.