From 0a4fe29ebe96b9743bb1a3bf00a9c387f511b8c3 Mon Sep 17 00:00:00 2001
From: Zev Spitz <shivisi@hotmail.com>
Date: Fri, 21 Jan 2022 04:52:44 +0200
Subject: [PATCH] Update README and add comments

---
 03_Animal/vbnet/Animal/Branch.vb |  1 +
 03_Animal/vbnet/Animal/Game.vb   | 30 ++++++++++++++++++++++++++++--
 2 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/03_Animal/vbnet/Animal/Branch.vb b/03_Animal/vbnet/Animal/Branch.vb
index 6734e39d..4af369bb 100644
--- a/03_Animal/vbnet/Animal/Branch.vb
+++ b/03_Animal/vbnet/Animal/Branch.vb
@@ -10,6 +10,7 @@
     Public Property Yes As Branch
     Public Property No As Branch
 
+    ' Allows walking all the descendants recursively
     Public Iterator Function DescendantTexts() As IEnumerable(Of String)
         If Yes IsNot Nothing Then
             Yield Yes.Text
diff --git a/03_Animal/vbnet/Animal/Game.vb b/03_Animal/vbnet/Animal/Game.vb
index 3bc2b2f6..bca72005 100644
--- a/03_Animal/vbnet/Animal/Game.vb
+++ b/03_Animal/vbnet/Animal/Game.vb
@@ -1,6 +1,8 @@
 Option Compare Text
 
 Public Class Game
+    ' This Dictionary holds the corresponding value for each of the variants of "YES" and "NO" we accept
+    ' Note that the Dictionary is case-insensitive, meaning it maps "YES", "yes" and even "yEs" to True
     Private Shared ReadOnly YesNoResponses As New Dictionary(Of String, Boolean)(StringComparer.InvariantCultureIgnoreCase) From {
         {"yes", True},
         {"y", True},
@@ -15,6 +17,8 @@ Public Class Game
     }
 
     ReadOnly console As ConsoleAdapterBase
+
+    ' The pre-initialized root branch
     ReadOnly root As New Branch With {
         .Text = "DOES IT SWIM?",
         .Yes = New Branch With {.Text = "FISH"},
@@ -41,6 +45,7 @@ Public Class Game
 
 
     Sub BeginLoop()
+        ' Print the program heading
         console.WriteCenteredLine("ANIMAL")
         console.WriteCenteredLine("CREATIVE COMPUTING  MORRISTOWN, NEW JERSEY")
         console.Write(
@@ -58,10 +63,16 @@ THINK OF AN ANIMAL AND THE COMPUTER WILL TRY TO GUESS IT.
 
             Dim response = console.ReadLine
             If response = "list" Then
+                ' List all the stored animals
                 console.WriteLine(
 "
 ANIMALS I ALREADY KNOW ARE:")
+
+                ' We're using a ForEach extension method instead of the regular For Each loop to provide the index alongside the text
                 root.DescendantTexts.ForEach(Sub(text, index)
+                                                 ' We want to move to the next line after every four animals
+                                                 ' But for the first animal, where the index is 0, 0 Mod 4 will also return 0
+                                                 ' So we have to explicitly exclude the first animal
                                                  If index > 0 AndAlso index Mod 4 = 0 Then console.WriteLine()
                                                  console.Write($"{text.MaxLength(15),-15}")
                                              End Sub)
@@ -76,10 +87,14 @@ ANIMALS I ALREADY KNOW ARE:")
 
             Dim currentBranch = root
             Do While Not currentBranch.IsEnd
+                ' Branches can either be questions, or end branches
+                ' We have to walk the questions, prompting each time for "yes" or "no"
                 console.Write($"{currentBranch.Text} ")
                 Do
                     ynResponse = GetYesNo()
                 Loop While ynResponse Is Nothing
+
+                ' Depending on the answer, we'll follow either the branch at "Yes" or "No"
                 currentBranch = If(
                     ynResponse,
                     currentBranch.Yes,
@@ -87,31 +102,42 @@ ANIMALS I ALREADY KNOW ARE:")
                 )
             Loop
 
-            'at end
+            ' Now we're at an end branch
             console.Write($"IS IT A {currentBranch.Text}? ")
             ynResponse = GetYesNo()
-            If ynResponse Then ' No difference between False or Nothing
+            If ynResponse Then ' Only if ynResponse = True will we go into this If Then
                 console.WriteLine("WHY NOT TRY ANOTHER ANIMAL?")
                 Continue Do
             End If
 
+            ' Get the new animal
             console.Write("THE ANIMAL YOU WERE THINKING OF WAS A ? ")
             Dim newAnimal = console.ReadLine
 
+            ' Get the question used to distinguish the new animal from the current end branch
             console.WriteLine(
 $"PLEASE TYPE IN A QUESTION THAT WOULD DISTINGUISH A 
 {newAnimal} FROM A {currentBranch.Text}")
             Dim newQuestion = console.ReadLine
 
+            ' Get the answer to that question, for the new animal
+            ' for the old animal, the answer would be the opposite
             console.Write(
 $"FOR A {newAnimal} THE ANSWER WOULD BE ? ")
             Do
                 ynResponse = GetYesNo()
             Loop While ynResponse Is Nothing
 
+            ' Create the new end branch for the new animal
             Dim newBranch = New Branch With {.Text = newAnimal}
+
+            ' Copy over the current animal to another new end branch
             Dim currentBranchCopy = New Branch With {.Text = currentBranch.Text}
+
+            ' Make the current branch into the distinguishing question
             currentBranch.Text = newQuestion
+
+            ' Set the Yes and No branches of the current branch according to the answer
             If ynResponse Then
                 currentBranch.Yes = newBranch
                 currentBranch.No = currentBranchCopy