Apologetic error messages
Following through on a naming idea by @huizendveld 2021-06-15 #naming #programming
Software sometimes models errors as exceptions, which represent conditions under which processing cannot continue normally. As with everything in software, exceptions need good names. In Naming pattern for Exceptions, Marijn Huizendveld proposes naming exceptions as apologies, which seems unusual enough to explore.
Apology naming style
Marijn starts with the suitably-Dutch situation of losing a bicycle, which results in a BikeCouldNotBeLocatedException.
Marijn argues for using language more naturally, and starting with an apology, especially since he lost someone else’s bike.
He proposes renaming:
BikeCouldNotBeLocatedException→SorryBikeCouldNotBeLocated.
While the conversational style holds some appeal, I prefer to name this kind of thing more conventionally, as noun phrases. This means renaming:
SorryBikeCouldNotBeLocated→BikeCouldNotBeLocatedApology
or even the more active renaming:
BikeCouldNotBeLocatedApology→ApologyForLosingTheBike
This preserves the idea that instead of modelling the undesirable condition (not knowing where I left the bike), politeness demands that I take responsibility for my inattentiveness. However, apologising takes more than calling something an apology.
6 elements of an effective apology
In An Exploration of the Structure of Effective Apologies (PDF) Roy Lewicki, Beth Polin and Robert Lount identify six components of an apology, and report that:
apologies with more components were more effective than those with fewer components, and certain components were deemed more important than others
The paper includes the following definitions:
| Apology component | Definition |
|---|---|
| Expression of regret | A statement in which the violator expresses how sorry they are for the offense |
| Explanation of what went wrong | A statement in which the reasons for the offense are described to the victim |
| Acknowledgment of responsibility | A statement which demonstrates the violator understands their part in the offense |
| Declaration of repentance | A statement in which the violator expresses their promise to not repeat the offense |
| Offer of repair | A statement extending a way to work toward trust rebuilding on the part of the violator |
| Request for forgiveness | A statement asking for the victim to pardon the violator’s actions |
Perhaps this explains why software routinely displays ineffective error messages: software design lacks an effective apology model.
An apology model for software errors
The elements of effective apologies teach us that a software developer who models an error condition must provide more structured information about the error, so that the software can translate this to a more complete error message, whose effectiveness will then depend on the underlying model.
A software error model therefore requires the following properties:
| Property | Values | Example |
|---|---|---|
| Explanation | Text summary of what went wrong | We lost your bike and our search of Amsterdam failed to locate it |
| Regret level | Number from 1 (sorry not sorry) to 10 (more sorry than about anything ever before) | 7 |
| Responsibility | Percentage of the blame assigned to the software | 90% |
| Repentance | Percentage likelihood that this will happen again | 5% |
| Repair | Text summary of measures taken to prevent reoccurrence | The error handler has fired the product manager, and the developers’ performance reviews will mention this incident |
The application user interface can then use this information to construct an appropriately apologetic error message that combines the text summaries with the standard text for each range of numeric values. Note that this model does not include the request for forgiveness, which belongs to error messages but does not depend on the specific error.
