diff --git a/10_Blackjack/java/src/Blackjack.java b/10_Blackjack/java/src/Blackjack.java
index 7552b02d..bc8c2194 100644
--- a/10_Blackjack/java/src/Blackjack.java
+++ b/10_Blackjack/java/src/Blackjack.java
@@ -8,11 +8,14 @@ public class Blackjack {
 	public static void main(String[] args) {
 		// Intuitively it might seem like the main program logic should be right
 		// here in 'main' and that we should just use System.in and System.out
-		// directly whenever we need them.  However, by externalizing the source
-		// of input/output data (and the ordering of the cards via a custom
-		// shuffle function), we can write non-interactive and deterministic
-		// tests of the code. See UserIoTest as an example.
-        try (Reader in = new InputStreamReader(System.in)) {
+		// directly whenever we need them.  However, notice that System.out and
+		// System.in are just an OutputStream and InputStream respectively. By
+		// allowing alternate streams to be specified to Game at runtime, we can
+		// write non-interactive tests of the code. See UserIoTest as an
+		// example.
+		// Likewise, by allowing an alternative "shuffle" algorithm, test code
+		// can provide a deterministic card ordering.
+		try (Reader in = new InputStreamReader(System.in)) {
 			Writer out = new OutputStreamWriter(System.out);
 			UserIo userIo = new UserIo(in, out);
 			Deck deck = new Deck(cards -> {
diff --git a/10_Blackjack/java/src/Game.java b/10_Blackjack/java/src/Game.java
index a79e986f..9ec64105 100644
--- a/10_Blackjack/java/src/Game.java
+++ b/10_Blackjack/java/src/Game.java
@@ -13,6 +13,9 @@ public class Game {
         this.userIo = userIo;
     }
 
+	/**
+	 * Run the game, running rounds until ended with CTRL+D/CTRL+Z or CTRL+C
+	 */
     public void run() {
 		userIo.println("BLACK JACK", 31);
 		userIo.println("CREATIVE COMPUTING  MORRISTOWN, NEW JERSEY\n\n\n", 15);
@@ -72,6 +75,10 @@ public class Game {
 
 			printInitialDeal(players, dealer);
 
+			// TODO check for dealer blackjack
+			//   if blackjack, print "DEALER HAS A [x] IN THE HOLE\nFOR BLACKJACK" and skip to evaluateRound
+			//   if not, print "NO DEALER BLACKJACK"
+
 			// TODO if dealer has an ACE, prompt "ANY INSURANCE" and deal with insurance
 
 			for(Player player : players){
@@ -86,6 +93,9 @@ public class Game {
 		}
     }
 
+	/**
+	 * Print the cards for each player and the up card for the dealer.
+	 */
 	private void printInitialDeal(List<Player> players, Player dealer) {
 		// Prints the initial deal in the following format:
 		/*
@@ -111,7 +121,7 @@ public class Game {
 			}
 			output.append("\n");
 		}
-		System.out.print(output);
+		userIo.print(output);
 	}
 
 	/**
@@ -160,10 +170,11 @@ public class Game {
 	}
 
 	/**
-	 * Calculates the value of a hand.
+	 * Calculates the value of a hand. When the hand contains aces, it will
+	 * count one of them as 11 if that does not result in a bust.
 	 * 
 	 * @param hand the hand to evaluate
-	 * @return The numeric value of a hand.
+	 * @return The numeric value of a hand. A value over 21 indicates a bust.
 	 */
 	protected int scoreHand(LinkedList<Card> hand){
 		int nAces = (int) hand.stream().filter(c -> c.getValue() == 1).count();
@@ -188,6 +199,7 @@ public class Game {
 	 * @return a negative integer, zero, or a positive integer as handA is less than, equal to, or greater than handB.
 	 */
 	private int compareHands(LinkedList<Card> handA, LinkedList<Card> handB) {
+		// TODO implement compareHands
 		return 0;
 	}
 
diff --git a/10_Blackjack/java/src/UserIo.java b/10_Blackjack/java/src/UserIo.java
index 57becd12..272614da 100644
--- a/10_Blackjack/java/src/UserIo.java
+++ b/10_Blackjack/java/src/UserIo.java
@@ -32,20 +32,42 @@ public class UserIo {
         this.out = new PrintWriter(out, true);
     }
 
+	/**
+	 * Print the line of text to output including a trailing linebreak.
+	 * 
+	 * @param text the text to print
+	 */
 	public void println(String text) {
 		out.println(text);
 	}
 
+	/**
+	 * Print the given text left padded with spaces.
+	 * 
+	 * @param text The text to print
+	 * @param leftPad The number of spaces to pad with.
+	 */
 	public void println(String text, int leftPad) {
 		IntStream.range(0, leftPad).forEach((i) -> out.print(' '));
 		out.println(text);
 	}
 
+	/**
+	 * Print the given text <i>without</i> a trailing linebreak.
+	 * 
+	 * @param text The text to print.
+	 */
 	public void print(String text) {
 		out.print(text);
 		out.flush();
 	}
 
+	/**
+	 * Reads a line of text from input.
+	 * 
+	 * @return The line entered into input.
+	 * @throws UncheckedIOException if the line is null (CTRL+D or CTRL+Z was pressed)
+	 */
 	private String readLine() {
 		try {
 			String line = in.readLine();
@@ -58,6 +80,12 @@ public class UserIo {
 		}
 	}
 
+	/**
+	 * Prompt the user via input.
+	 * 
+	 * @param prompt The text to display as a prompt. A question mark and space will be added to the end, so if prompt = "EXAMPLE" then the user will see "EXAMPLE? ".
+	 * @return The line read from input.
+	 */
 	public String prompt(String prompt) {
 		print(prompt + "? ");
 		return readLine();