diff --git a/src/middleware/updateURLMiddleware.js b/src/middleware/updateURLMiddleware.js
index 54b3bc94..dce604a7 100644
--- a/src/middleware/updateURLMiddleware.js
+++ b/src/middleware/updateURLMiddleware.js
@@ -13,7 +13,12 @@ const updateURLMiddleware = (store) => {
 
       const state = store.getState();
 
-
+      /************************************************************************
+      *************************************************************************
+      1. The state just changed. Clear, and then update, the URL.
+      1a. We get the whole state tree to construct the url from      
+      *************************************************************************
+      ************************************************************************/
 
       // const oldURI = URI(window.location.href)
       // const newURI = URI(oldURI).setQuery({})
diff --git a/src/reducers/url.js b/src/reducers/url.js
index e1d50e85..19a76e73 100644
--- a/src/reducers/url.js
+++ b/src/reducers/url.js
@@ -1,7 +1,15 @@
 import uri from "urijs";
-/*
-  https://www.npmjs.com/package/url-parse
-*/
+
+/************************************************************************
+*************************************************************************
+# This is all of the state that will be stored in the URL query params.
+# It is reasonably important it be kept in the same place,
+because if initial load or back button etc, we'll hear about that
+and manually reconstruct the state from the url, overriding whatever
+we had. We could of course listen for the "url changed" type in another
+reducer, if this gets messy.
+*************************************************************************
+************************************************************************/
 
 const url = (
   state = {},