Writing good error messages
Agenda
- Background
- The consumers of the error messages
- What are good error messages
- Tips for good error messages
- Recap
Background
| DSSServerDispatcher. error dispatching request -1. err = 0x800436F8. |
|---|
| The object with the given identifier is not an object of the expected type. |
| Index out of range |
| Item not found in this collection. Container ID: %1, Object ID: %2. |
| Form (1) is not included on the template. |
| Skipping broken internal reference |
| Object Second Class has already been deleted or is in an invalid state. |
| Invalid Expression. |
| Index out of range in method 'LeanCollection::ItemNS' |
The consumers of errors
- End user
- Administrator
- Support/engineering
- ...
What are good error messages
- WHY it went wrong and the action can’t proceed?
- HOW the error was detected/triggered?
- WHAT can be done to resolve it?
- WHEN did the error happen?
- WHO was trying to achieve the goal?
Tips for good error messages
Be clear and not ambiguous
- Invalid Expression.
- Error detected while parsing expression for derived attribute: Specifying the sorting direction (Asc or Desc) is not allowed for dynamic sorting.
Be short and meaningful
- Failed to connect to data source. Error message: Connect failed. {Error type: Odbc error. Odbc operation attempted: SQLDriverConnect. [HY000:98: on SQLHANDLE] [MicroStrategy][ODBC Salesforce driver][Salesforce]java.io.FileNotFoundException: /opt/mstr/MicroStrategy/IntelligenceServer/svcappin.config (No such file or directory) Connection String: DSN=SalesForce_PROD;UID=svcappin@microstrategy.com;. }
- Failed to connect to data source. {Error type: Odbc error. Odbc operation attempted: SQLDriverConnect. ...}
Don’t use technical jargons
- QueryEngine::RunSQLParallelWrapper, retry: 3, Action: 22, CubeID: 3DF3BD6011E8267D7A150080EF1594ED, Match:false
- Server encountered an error when executing SQLs in parallel. Details for trouble shooting: {QueryEngine::RunSQLParallelWrapper, retry: 3, Action: 22, CubeID: 3DF3BD6011E8267D7A150080EF1594ED, Match:false}
Be Humble — Don’t Blame User
- You have entered an illegal object name character.
- The object name contains illegal characters.
Give Direction to User
- curl_easy_perform failed. Error Code: 7.
- Failed to connect to host or proxy. Please check your network connection to 'XXX'. Details for trouble shooting: {curl_easy_perform failed. Error Code: 7.}
Avoid Uppercase Text
- FAILED SUBSCRIPTION. ...
- Failed subscription. ...
Recap
- Make sure your error messages are targeted for the right consumer.
- Add adequate informaito to the message
- Why, how, what
- When, who
- Follow the tips to make the error message professional.
Writing good error messages
By bawu
Writing good error messages
- 7
