Before we get to the fun part of the course—wording error messages—let's discuss a few general error handling rules.
Don't fail silently
Failure is inevitable; failing to report failures is inexcusable. Failing silently causes the following problems:
- Users wonder whether something has gone wrong. ("Why did my order not go through?")
- Customer support wonders what caused a problem. ("The log file gave no indication of a problem.")
Embrace your software's fallibility. Assume that humans will make mistakes using your software. Try to minimize ways for people to misuse your software, but assume that you can't completely eliminate misuse. Therefore, plan error messages as you design software.
Follow the programming language guides
Follow the guidelines on error handling in Google's programming language guides, including:
- Google C++ Style Guide
- Google Java Style Guide
- Google Python Style Guide, particularly the Error Messages section
- Google JavaScript Style Guide
- Google Go Style Guide, particularly the Error handling section
Implement the full error model
Implement the full error model described in the Errors page of the Google AIP. For instance, note the following quote about implementing error messages in services:
Services must return a google.rpc.Status message when an API error occurs, and must use the canonical error codes defined in google.rpc.Code.
The Errors page of the Google Cloud API design guide provides helpful information about implementing the full error model for Google APIs.
Avoid swallowing the root cause
API implementations should not swallow the root cause of issues occurring in the back end. For example, many different situations can cause a "Server error" problem, including:
- service failure
- network connection drop
- mismatching status
- permission issues
"Server error" is too general an error message to help users understand and fix the problem. If the server logs contain identification information about the in-session user and operation, we recommend providing additional context on the particular failure case.
Log the error codes
Numeric error codes help customer support monitor and diagnose errors. Consequently, specifying numeric error codes along with textual error messages is often quite valuable.
You can specify error codes for both internal and external errors. For internal errors, provide a proper error code for easy lookup/debugging by internal support personnel and engineers.
Document all error codes.
Raise errors immediately
Raise errors as early as useful. Holding on to errors and then raising them later increases debugging costs dramatically.
Next unit: Identify the error's cause