Nobody reads it when things go right.
It waits in the dark,
for the worst day,
for the tired person at the wrong hour.
That person is often you.
The error message is not decoration.
It is the one sentence you get
to speak to someone who is already frustrated.
So do not spend it on "an error occurred."
That tells them nothing they did not already know.
A good message says three things.
What broke.
Where you were when it broke.
What they might try next.
"Failed" is a shrug.
"Failed to connect to billing at 10.0.0.4: timeout after 5s" is a hand on the shoulder.
The first makes them guess.
The second makes them move.
Write the message for the person who has no context.
Not the one who wrote the code.
The one who inherited it,
at 3 a.m.,
with a pager still buzzing.
Stack traces are for you.
Messages are for them.
Do not leak the secret into the log
just because it would be handy.
Do not swallow the cause
just to keep the output tidy.
The tidiest log is the one that hides why.
Every silent catch
is a message you decided not to send.
Somebody will need that message.
They will need it more than you needed the clean screen.
Great code fails loudly and kindly.
It names the thing.
It points a direction.
It refuses to leave you alone in the dark.
Fragile code fails politely and uselessly,
and lets you find out in production
what it could have told you in a line.
Write the message you would want
on the night you understand nothing
and the fix is due by morning.
That message is a gift
you send backward in time,
to a stranger who is you.
– Serguey Asael Shinder
