TicTacToe rule notes

Author: mwunderl

src/main/java/scorekeep/TicTacToe.java

@@ -8,13 +8,23 @@
 public class TicTacToe {
   private static final Logger logger = LoggerFactory.getLogger("TicTacToe");
 
+  /* State is a string with one character that indicates the current turn
+   * (X or O), or win state (A or B). The remaining 9 characters map to spaces
+   * on the game board.
+   *        1 2 3
+   *        4 5 6
+   *        7 8 9
+   * A move is a two character string that indicates the moving player (X or O)
+   * and the space on the game board. After applying the move, the function
+   * converts the game state of the current player into an integer and compares
+   * it against known win states to check for victory.
+   */
   public static String move(String oldState, String moveText) {
-    // 0: user, 1-9: board 
-    // String old = "XNNNNNNNNN";
-    // 0: turn, 1: space
-    // String mov = "X3";
+    // current state in char[]
     char[] oldchar = oldState.toCharArray();
+    // move in char[]
     char[] movchar = moveText.toCharArray();
+    // validate move and update state
     if ( movchar[0] == oldchar[0] ) {
       oldchar[Character.getNumericValue(movchar[1])] = movchar[0];
       if ( movchar[0] == 'X' ) {
@@ -25,12 +35,10 @@ public static String move(String oldState, String moveText) {
     } else {
       logger.error("Not your turn");
     }
-    // new = "ONNXNNNNNN" 
-    // check for victory
-    // - convert state to integer
+    // convert state to integer
     int stateInt = toInt(oldchar, movchar[0]);
     logger.info("state int: " + stateInt);
-    // - compare
+    // check for victory
     boolean win = checkWin(stateInt);
     if ( win ) {
       if ( movchar[0] == 'X') {
@@ -43,6 +51,10 @@ public static String move(String oldState, String moveText) {
     return newState;
   }
 
+  /* Convert a string game state to an integer by treating it as a binary
+   * number where spaces occupied by the player are '1' and all other spaces
+   * are '0'.
+   */
   public static int toInt(char[] state, char turn) {
     int out = 0;
     int len = state.length;
@@ -54,6 +66,14 @@ public static int toInt(char[] state, char turn) {
     return out;
   }
 
+  /* Compare an integer game state against known winning states for tic tac
+   * toe. For example, X can win with three Xs on the bottom row:
+   *        0 X 0
+   *          O
+   *        X X X
+   * Xs state in binary is 010000111, 135 in decimal. 135 is a bitwise match
+   * for 000000111, 7 in decimal, one of the 8 winning states.
+   */
   public static boolean checkWin(int state) {
     int[] winningStates = {7,56,73,84,146,273,292,448};
     for ( int i = 0; i < 8; i++ ){