Feature/integrate ians comments branch

integrate all of the crits from the beautiful and erudite [Ian](https://github.com/ianstormtaylor)'s code review.