some commentary to clarify what does what, and drying some code out for random data