Writing by Peter Hilton

Apologetic error messages

Following through on a naming idea by @huizendveld 2021-06-15 #naming #programming

unsplash-logoTamas Munkacsi

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:


While the conversational style holds some appeal, I prefer to name this kind of thing more conventionally, as noun phrases. This means renaming:


or even the more active renaming:


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.

Share on TwitterShare on LinkedIn