improve comments and error messages