improved comments and error messages