refactor

commenting, naming, and reorganization to make the script more friendly
for the team as a whole.