minor refactor to improve comments and error recovery