comments + code clarity edits

mostly done, not sure about some of the solutions