improve code quality by extracting verbose logic, DRYing up logic, parameterizing constants, adding doc