Addressing comments in issue #10

doug-martin · doug-martin · commit 9da63cccddff · 2012-11-02T01:56:12.000-05:00
diff --git a/labs/data_storage.md b/labs/data_storage.md
@@ -12,7 +12,7 @@
 - How to store data to mongo.
 - How to retrieve data from mongo.
 - How to run other actions.
-    *  	Map Reduce
+    *     Map Reduce
 
 ## Lab
 
@@ -31,11 +31,18 @@
        }
    }
    ```
-
+   **Note** You could put this in your `index.js` file but it is good practice to keep configuration variables out of your source so you can easily change them later.  
 
 5. Create a file named `index.js`
 
-   At the top of the file require your `config.json` so we can get our connection information.
+   First add `"use strict"` to the top of the file to prevent us from doing anything crazy like exporting a global variable!
+   
+   ```javascript
+   "use strict";
+   ```
+
+   Next require your `config.json` so we can get our connection information.
+   
 
    ```javascript
    "use strict"
@@ -44,18 +51,21 @@
 
    Next we'll get our mongo Classes
 
-   ```
+   ```javascript
    "use strict"
    var CONFIG = require("./config.json").connection,
        mongodb = require('mongodb'),
        Db = mongodb.Db,
-       Connection = mongodb.Connection,
        Server = mongodb.Server;
    ```
 
-6. Create a domain to catch errors from out mongo code.
+   * `Server` : This class represents the mongodb server 
+   * `Db` : This is the class that represents a database on the mongodb `Server`
 
-   The domain will allow us to catch all errors in a single place and know where the errors came from.
+6. Create a domain to catch errors from our mongo code.
+
+
+   A domain allows to handle all IO operations as a single group. In this case we want all of our mongo actions to happen in the `mongoDomain` allowing us to catch all errors in a single place. To read more about domains go [here](http://nodejs.org/api/domain.html).
 
 
    ```javascript
@@ -66,46 +76,48 @@
        console.error('Mongo error!', er);
    });
 
-   mongoDomain.run(function () {
-       var db = new Db(CONFIG.dbName, new Server(CONFIG.host, CONFIG.port, {safe:true}));
-   });
    ```
+   
+   Notice how we create a new variable [`intercept`](http://nodejs.org/api/domain.html#domain_domain_intercept_callback) to which is bound to the `mongoDomain` scope. This allows us to reference `intercept` without having to type `mongoDomain.intercept` everytime.
 
-7. Now lets create our connetion to `mongo`
+7. Now lets create our connection to `mongo`   
 
    ```javascript
    mongoDomain.run(function () {
        var db = new Db(CONFIG.dbName, new Server(CONFIG.host, CONFIG.port, {safe:true}));
    });
 
-
    ```
 
+   **Note** At this point we are not connnected to the server.
 
-8. Lets insert some data into mongo.
+
+8. Lets insert some data into `mongo`.
 
    We are going to be inserting a list of users into this database. The data can be found [here](../examples/mongo/assets/users.json)
 
 
-   To insert into mongo we need to get a collection, so lets create a function that will automatcially intercept the callback and retrieve the collection.
+   To insert into mongo we need to get a collection, so lets create a function that will automatcially intercept the callback and retrieves the collection.
 
    ```javascript
    function getCollection(collection, cb) {
-   	db.collection(collection, intercept(cb));
+      //use intercept to allow us to catch errors
+      db.collection(collection, intercept(cb));
    }
-   ```
+   ```   
 
    Next lets use `getCollection` in our `insert` function.
 
    ```javascript
    function insert(cb) {
-       //get our users data
-   	var users = require("./assets/users.json");
-   	//get the "users collection"
-       getCollection("users", function (collection) {
-           //insert the users
-           collection.insert(users, intercept(cb));
-       });
+      //get our users data
+      var users = require("./assets/users.json");
+      //get the "users collection"
+      getCollection("users", function (collection) {
+         //insert the users
+         //use intercept to allow us to catch errors
+         collection.insert(users, intercept(cb));
+      });
    }
    ```
 
@@ -115,20 +127,21 @@
    //be sure to open your connection
    db.open(intercept(function () {
        //insert our data
-   	insert(function () {
-   	    //we inserted our users!
-   		console.log("Inserted Users!");
-    	});
+      insert(function () {
+         //we inserted our users!
+         console.log("Inserted Users!");
+      });
    }));
    ```
 
-9. Ok now we can insert we should be able to remove the data.
+9. Ok now that we can insert data we should be able to remove the data too.
 
    ```javascript
    function remove(cb) {
        getCollection("users", function (collection) {
+            //use intercept to allow us to catch errors
             collection.remove(intercept(cb));
-   	});
+       });
    }
    ```
 
@@ -137,19 +150,19 @@
 
    ```javascript
    function reset(cb) {
-   	remove(function () {
-   		insert(cb);
-   	});
+      remove(function () {
+         insert(cb);
+      });
    }
    ```
 
-11. Ok lets add a method `count` our data.
+11. Ok lets add a method to `count` the number of users in `mongo`.
 
    ```javascript
    function getCount(cb) {
-   	getCollection("users", function (collection) {
-   		collection.count(intercept(cb));
-   	});
+      getCollection("users", function (collection) {
+         collection.count(intercept(cb));
+      });
    }
    ```
 
@@ -203,29 +216,35 @@
    });
    ```
 
-13. Now lets add a function to get the count of each users based on the first letter of their first name. To do this we will need to use the [MapReduce](http://www.mongodb.org/display/DOCS/MapReduce).
+13. Next lets add a function that aggregates the users by the first letter in their `firstName` property. To do this we will need to use the [MapReduce](http://www.mongodb.org/display/DOCS/MapReduce).
 
    ```javascript
-    var getCountByFirstName = (function getCountByFirstName() {
-   	function map() {
-   		if (this.firstName) {
-   			emit(this.firstName.charAt(0), 1);
-   		}
-   	}
-
-   	function reduce(key, values) {
-   		return values.length;
-   	}
-
-   	return function _getCountByFirstName(cb) {
-   		getCollection("users", function getUsersCollection(collection) {
-   			collection.mapReduce(map, reduce, {out:{inline:1}}, intercept(cb));
-   		});
-   	};
+   var getCountByFirstName = (function getCountByFirstName() {
+      function map() {
+         if (this.firstName) {
+            emit(this.firstName.charAt(0), 1);
+         }
+      }
+
+      function reduce(key, values) {
+         return values.length;
+      }
+
+      return function _getCountByFirstName(cb) {
+         getCollection("users", function getUsersCollection(collection) {
+            collection.mapReduce(map, reduce, {out:{inline:1}}, intercept(cb));
+         });
+      };
    }());
 
    ```
 
+   What is that function wrapped in parens? That is called an `IIFE` (Immediatly Invoked Function Expression). This allows us to keep `map` and `reduce` private while exposing the `_getCountByFirstName` function. So `getCountByFirstName` is actually assigned to `_getCountByFirstName` while not exposing the private `map` and `reduce` functions.
+
+   **Note** the `map` and `reduce` functions are not executed in `node` they are actually serialzed by calling the `toString` and sent to `mongo` to execute on the server. So you **cannot** use any variables that would normally be available (i.e. closure varibles).
+
+   Notice how we pass in `{out : {inline : 1}}` this tells mongo to do the map reduce in memory. 
+
    Now lets use it and see what we get!
 
    ```javascript
