self code-review: removing cruft, adding more comments, cleaning questionable structure