Code comments.

tolerant-reader/src/main/java/com/iluwatar/App.java

@@ -4,7 +4,17 @@ import java.io.IOException;
 
 /**
  * 
+ * Tolerant Reader is an integration pattern that helps creating robust communication
+ * systems. The idea is to be as tolerant as possible when reading data from another
+ * service. This way, when the communication schema changes, the readers must not break.
  * 
+ * In this example we use Java serialization to write representations of RainbowFish
+ * objects to file. RainbowFish is the initial version which we can easily read and
+ * write using RainbowFishSerializer methods. RainbowFish then evolves to RainbowFishV2
+ * and we again write it to file with a method designed to do just that. However, the reader
+ * client does not know about the new format and still reads with the method designed for
+ * V1 schema. Fortunately the reading method has been designed with the Tolerant Reader
+ * pattern and does not break even though RainbowFishV2 has new fields that are serialized.
  *
  */
 public class App {

tolerant-reader/src/main/java/com/iluwatar/RainbowFish.java

@@ -2,6 +2,11 @@ package com.iluwatar;
 
 import java.io.Serializable;
 
+/**
+ * 
+ * RainbowFish is the initial schema
+ *
+ */
 public class RainbowFish implements Serializable {
 
 	private static final long serialVersionUID = 1L;

tolerant-reader/src/main/java/com/iluwatar/RainbowFishSerializer.java

@@ -9,8 +9,21 @@ import java.io.ObjectOutputStream;
 import java.util.HashMap;
 import java.util.Map;
 
+/**
+ * 
+ * RainbowFishSerializer provides methods for reading and writing RainbowFish objects to file.
+ * Tolerant Reader pattern is implemented here by serializing maps instead of RainbowFish objects.
+ * This way the reader does not break even though new properties are added to the schema.
+ *
+ */
 public class RainbowFishSerializer {
 
+	/**
+	 * Write V1 RainbowFish to file
+	 * @param rainbowFish
+	 * @param filename
+	 * @throws IOException
+	 */
 	public static void writeV1(RainbowFish rainbowFish, String filename) throws IOException {
 		Map<String, String> map = new HashMap<>();
 		map.put("name", rainbowFish.getName());
@@ -24,6 +37,12 @@ public class RainbowFishSerializer {
 		fileOut.close();
 	}
 
+	/**
+	 * Write V2 RainbowFish to file
+	 * @param rainbowFish
+	 * @param filename
+	 * @throws IOException
+	 */
 	public static void writeV2(RainbowFishV2 rainbowFish, String filename) throws IOException {
 		Map<String, String> map = new HashMap<>();
 		map.put("name", rainbowFish.getName());
@@ -40,6 +59,13 @@ public class RainbowFishSerializer {
 		fileOut.close();
 	}
 	
+	/**
+	 * Read V1 RainbowFish from file
+	 * @param filename
+	 * @return
+	 * @throws IOException
+	 * @throws ClassNotFoundException
+	 */
 	public static RainbowFish readV1(String filename) throws IOException, ClassNotFoundException {
 		Map<String, String> map = null;
 		FileInputStream fileIn = new FileInputStream(filename);

tolerant-reader/src/main/java/com/iluwatar/RainbowFishV2.java

@@ -1,5 +1,10 @@
 package com.iluwatar;
 
+/**
+ * 
+ * RainbowFishV2 is the evolved schema
+ *
+ */
 public class RainbowFishV2 extends RainbowFish {
 
 	private static final long serialVersionUID = 1L;