Added and clarified some code comments

newcache.py

@@ -88,6 +88,8 @@ def _get_memcache_timeout(self, timeout):
         return timeout
 
     def add(self, key, value, timeout=None, herd=True):
+        # If the user chooses to use the herd mechanism, then encode some
+        # timestamp information into the object to be persisted into memcached
         if herd:
             packed = (value,
                 (timeout or self.default_timeout) + int(time.time()))
@@ -123,6 +125,8 @@ def get(self, key, default=None):
         return val
 
     def set(self, key, value, timeout=None, herd=True):
+        # If the user chooses to use the herd mechanism, then encode some
+        # timestamp information into the object to be persisted into memcached
         if herd:
             packed = (value,
                 (timeout or self.default_timeout) + int(time.time()))
@@ -175,7 +179,8 @@ def get_many(self, keys):
                 self._get_memcache_timeout(CACHE_HERD_TIMEOUT))
 
         # Build a reverse map of encoded keys to the original keys, so that
-        # the dictionary keys are what users expect.
+        # the returned dict's keys are what users expect (in that they match
+        # what the user originally entered)
         reverse = dict(zip(rvals, keys))
 
         return dict(((reverse[k], v) for k, v in resp.iteritems()))