You’ve just joined a new company, and you’re reading through their code when you come across some debug logging.

Why is it there?

In my experience, most developers don’t think about this. And this is a problem.

The vast majority of debug logging I see in active code bases is cruft. It ought to be removed. But to understand why, I think we need to first look at two (mostly) legitimate reasons for debug logs.

1. Debug logs are useful for blackbox debugging

   When used for blackbox debugging, there is no assumption that the person debugging has (or should have) any intimate knowledge of the internals of the system.

   This is useful for standard command-line or desktop apps. For example, ssh -vvv.

   The important thing to recognize here is that (usually) this type of debugging output does not exist to debug the program itself (ssh in this example), but it exists to help debug a larger process (i.e. network communication). As such, it needs to be well written, (grammar/spell check advised), clear, and descriptive, because it’s part of the program’s UI.

   This type of debug output is pretty rare in the code I tend to work on, which is server backend processes. And that’s as it should be, because there are no operators of the software who don’t (or shouldn’t) have an intimate knowledge of how it works.

2. Debug logs are useful for active debugging

   In other words, you’re using debug lines as a sort of interactive debugger. print("here!") type of stuff.

   This is by far the most common type of debugging output I see in the code I work with.

   And there’s nothing, per se, wrong with this type of debugging output. Sometimes it’s essential.

   However, once a particular bug is solved, the value of such debugging output drops to practically zero, or often even lower (that is, it becomes a liability). Which is when it becomes cruft…

If you’re using debugging output to debug a particular bug, a good rule is to clean up that debugging output before committing, or to clean it up shortly after.