The Pragmatic Craftsman :: Simplicity from complexity : by Stanley Kubasek ::

Write Debuggable Code!

“One of the differences between a great programmer and a bad programmer is that a great programmer adds logging and tools that make it easy to debug the program when things fail.” [reference below]

I’m sure you’ve experienced a good share of mystery/quiet/business-as-usual failures.

Wouldn’t it be nice to have code that is smart to detect error conditions and make it obvious?

There are many ways of doing the communication. Some are trivial and easy to do. Some require extra thinking. Some require that extra step — step which is not in acceptance criteria. :)

Logging is one. It falls under the “trivial and easy to do” category. I feel we’re not utilizing it to its full potential. I’ve seen many instances where error conditions are not visible in logs. When we debug issues everything works as expected. So it seems… Then what? We need to keep digging. We’ve got to turn into code and look for clues. It’s time consuming. It’s frustrating. Wouldn’t it be better if we got a clue from the log?

“When the program works as expected, there is often no difference in the quality of the logging. However, as soon as the program fails, or you get the wrong result, you can almost immediately tell the good programmers from the bad.” [same reference]

Exactly. Logging gets a bad rap. But it’s invaluable in situations like those. It’s a great lead in finding the underlying cause of the issue.

So think about those error conditions. Check that the object you’re working on is in a “correct” state and if not add a warning message. Those warning and debug statements serve as an excellent documentation tool! Think of them as live comments.

Most of our loggers are accessible via JMX. That means no restart is required to change a log level. Very convenient!

There is really no reason why all of us should not be utilizing logging.

Logging is just one way. There are other ways. Think of stats/counters/jmx/dashboards. These require that extra effort and thought but are critical in communicating the health of the system. And there are cases where logging might be excessive when we expect an error to happen frequently. It’d be better to 1) output a message about a fail rate once a minute or so and 2) have stats accessible via jmx/dashboard. That allows us to see if the feature we built is working as expected, but also monitor performance/usage/etc.

I’m sure there are other ways.

But the bottom line is that we shouldn’t just be asking “does it work?” but how am I going to debug it things don’t work? How is it going to respond to error conditions? How am I going to validate that it actually does work?

If you learn to write debuggable code there are a few things that will happen.

1) You will become a better programmer
You’ll start thinking of the end result. You’ll cover the edge cases and “share” those unexpected values/conditions. You’ll be delivering smarter and friendlier code.

2) You’ll reap the benefits when debugging issues
It’ll happen. It’ll happen sooner than you think. And you’ll be thankful that you or somebody else took the extra care and added those debug statements/stats/etc.

Writing debuggable code takes effort and skill. But those extra steps, that extra effort is what distinguishes the good from the best.

Great Programmers Write Debuggable Code

Favorite Quote




Currently Reading


© 2001-2024 Stanley Kubasek About me :: Contact me

Me on Twitter

»see more

Recent Entries