Stop Writing Creative Log Messages

Save the prose for your poetry

Photo by Marko Horvat on Unsplash

If you work long enough as a software engineer, you’ll see them. Those “funny” log messages sprinkled throughout your company’s codebase. A line written by someone who wanted to show that they’re a humorist as well as an engineer. Something like:

log.error(
  "Couldn’t find the server. Guess it went on vacation!!! :)" );

Maybe you’ll chuckle to yourself the first time you see it in code. But be assured, there will be no chuckling when you’re dealing with a production outage, and that is the data to which your hopes of a quick resolution are pinned.

At this point, the urge to find the engineer who wrote this message—and pop them in their smug, wanna-be comedian face—might be strong. But let’s be honest: we’ve all written log messages like this. Ones that—if not quite as “funny” — were just as frustratingly useless. Undoubtedly, if faced with seeing some our own messages in production, we’d wish we could slink back in time and rewrite them.

So why do we continue to be so glib with our log messages?

I contend that its simply because we focus on solving our own immediate needs. Instead, we should be solving the needs of the future engineer (who might turn out to be us!) who will be consuming our logs.

Solving our immediate needs

We tend to view writing logs as a necessary evil. As we write code, we’ll hit a point where we feel pressured to tell someone that something has happened. Often this point is prompted by catching an exception. For example, imagine writing code like the following:

var connection = getConnection();
try {
  var personResponse = connection.get("/persons/" + id);
  var b = validate(personResponse);
  return (b) ? personResponse : null;
} catch (IOException e) {
  //TODO do something
}

As experienced engineers, we innately know that we cannot leave that seventh line as a TODO comment. We need to handle it somehow.

So we write a log message. But let’s be honest. Composing a log message feels like a disruption from our “real” programming work. We want to get in and get out as speedily as possible. And so, we quickly type up a…