code cleanup: added comments and consolidated code into more abstract methods