more commentary

Author: Banyc

README.md

@@ -62,12 +62,32 @@ drop database DATABASE_NAME
 show tables;
 ```
 
+## Terminology
+
+- file := the database file
+- file header := the header in the database file
+- table tree := the B+ tree designed to represent a table
+- index tree := the B+ tree designed to represent an index
+
 ## Spec
 
 ### Database File Format
 
 The database file format mimicked that of SQLite but with some differences. 
 
+Differences:
+
+- the file headers omits many fields.
+- Index tree is also implemented with B+ tree, not B tree.
+- Index tree utilizes `InternalTableCell` and `LeafTableCell` rather than `InternalIndexCell` and `LeafIndexCell`. In order words, index trees have the same architecture as table trees. 
+- Index tree could only support dropping and inserting along with the table tree but not deleting due to complicity (implemented in `DatabaseController`).
+- The `key` field of the table cells is implemented with type `DBRecord`, not `int`.
+
+Learn more from:
+
+- with graph - <http://chi.cs.uchicago.edu/chidb/fileformat.html>
+- official - <https://www.sqlite.org/fileformat.html>
+
 ### 数据类型
 
 只要求支持三种基本数据类型：int，char(n)，float，其中char(n)满足 1 <= n <= 255 。

src/MiniSQL.BufferManager/Controllers/FreeList.cs

@@ -3,7 +3,7 @@
 
 namespace MiniSQL.BufferManager.Controllers
 {
-    // a link list recording all free pages
+    // a linked list recording all free pages
     public class FreeList
     {
         private readonly Pager _pager;

src/MiniSQL.BufferManager/Models/FreeListTruck.cs

@@ -2,6 +2,9 @@
 
 namespace MiniSQL.BufferManager.Models
 {
+    // To keep MemoryPage intact with new functionality, 
+    //  FreeListTruck here is to wrap up the MemoryPage.
+    // a minimal unit in the FreeList
     public class FreeListTruck
     {
         private readonly MemoryPage _page;

src/MiniSQL.Client/Controllers/View.cs

@@ -3,6 +3,7 @@
 using System.Diagnostics;
 using System.Text;
 using System.Text.RegularExpressions;
+using MiniSQL.Client.Helpers;
 using MiniSQL.Library.Exceptions;
 using MiniSQL.Library.Interfaces;
 using MiniSQL.Library.Models;
@@ -162,7 +163,7 @@ private static void PrintRows(SelectResult result)
                 string format = "{0, " + (-sizes[columnIndex]).ToString() + "}";
                 Console.Write($" {string.Format(format, name.AttributeName)} ");
                 if (columnIndex < result.ColumnDeclarations.Count - 1)
-                    Print("|", ConsoleColor.DarkGray);
+                    PrintHelper.Print("|", ConsoleColor.DarkGray);
                 columnIndex++;
             }
             Console.WriteLine();
@@ -192,7 +193,7 @@ private static void PrintRows(SelectResult result)
                     }
                     Console.Write($" {string.Format(format, stringToPrint)} ");
                     if (columnIndex < row.Count - 1)
-                        Print("|", ConsoleColor.DarkGray);
+                        PrintHelper.Print("|", ConsoleColor.DarkGray);
                     columnIndex++;
                 }
                 Console.WriteLine();
@@ -236,16 +237,5 @@ private static List<int> GetColumnSize(SelectResult result)
             }
             return sizes;
         }
-
-        private static void Print(string toPrint, ConsoleColor color)
-        {
-            // change color
-            ConsoleColor defaultColor = Console.ForegroundColor;
-            Console.ForegroundColor = color;
-            // print
-            Console.Write(toPrint);
-            // restore the previous color
-            Console.ForegroundColor = defaultColor;
-        }
     }
 }

src/MiniSQL.Client/Helpers/PrintHelper.cs

@@ -0,0 +1,18 @@
+using System;
+
+namespace MiniSQL.Client.Helpers
+{
+    public static class PrintHelper
+    {
+        public static void Print(string toPrint, ConsoleColor color)
+        {
+            // change color
+            ConsoleColor defaultColor = Console.ForegroundColor;
+            Console.ForegroundColor = color;
+            // print
+            Console.Write(toPrint);
+            // restore the previous color
+            Console.ForegroundColor = defaultColor;
+        }
+    }
+}