On writing code with debugging in mind

*                                                *
* .=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-. *
* |                   ______                   | *
* |                .-"      "-.                | *
* |               /            \               | *
* |   _          |              |          _   | *
* |  ( \         |,  .-.  .-.  ,|         / )  | *
* |   > "=._     | )(__/  \__)( |     _.=" <   | *
* |  (_/"=._"=._ |/     /\     \| _.="_.="\_)  | *
* |         "=._"(_     ^^     _)"_.="         | *
* |             "=\__|IIIIII|__/="             | *
* |            _.="| \IIIIII/ |"=._            | *
* |  _     _.="_.="\          /"=._"=._     _  | *
* | ( \_.="_.="     `--------`     "=._"=._/ ) | *
* |  > _.="                            "=._ <  | *
* | (_/                                    \_) | *
* |                                            | *
* '-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=' *
*                                                *
ASCII art image of a skull and crossbones with the text “abandon all hope, all ye who enter here” displayed below the skull and crossbones.

One factor of code quality that does not get enough attention is how easy is it to debug the code. No matter how skilled the team that writes the software, there will be bugs. When these bugs are found some poor soul will need to debug the code to determine the cause of the bug. Unfortunately this can quickly turn into a nightmare because many functions are not debuggable. Sometimes even well designed code is so difficult to debug that it causes the poor soul who has to debug it to abandon all hope.

Non-Debuggable Function

The following function is very simple. At first glance it seems to be a concise and well designed function. However, it is a major contributor to the debugging this application is a nightmare problem.

inline bool CCoolAppDocument::IsValidStartOffset(long nOffset) const
    return nOffset >=0 && nOffset < GetLength();

You may be wondering, how can this innocent, one-line function cause someone to abandon all hope?

When the function works as expected (meaning it returns the value you expect) it cannot. However, when the function returns false when you think it should return true the nightmare begins. The most critical piece of information that might explain why this function is not returning the expected value, the document length, is hidden away within a function call. As a result, there is no way you can look at parameter and variable values in the debugger watch window and know why the function is behaving in the way that it is.

Debuggable Function

The following function does exactly the same thing but it can be debugged in a microsecond.

inline bool CCoolAppDocument::IsValidStartOffset(long nOffset) const
    const auto documentLength = GetLength();
    return (nOffset >=0 && nOffset < documentLength);

All you have to do to debug this function is look at the value of the nOffset parameter and the documentLength variable in the watch window and then the reason for the unexpected behavior is immediately obvious.

In the case of today’s nightmare that inspired this article, the problem was that both the nOffset parameter and the documentLength variable happened to be equal to 296.

Additional Comments

I know that some of you are wondering whether I am aware that some debuggers will provide the return value of a function that was just called. The answer is of course I am aware of that. However, as far as I know not all debuggers support this functionality. In addition, this functionality is not as easy to use or as intuitive as the watch variable feature.

To me it just makes sense to make a very small change to make it possible to diagnose problems with the more intuitive and easier to use watch variable feature of the debugger.


Is the Novel coronavirus (COVID-19) contained in the United States?

Meme showing a dog sitting at a table. The room is on fire. The dog says 'This is fine'.
This is fine.

On March 6, 2020, President Donald Trump’s top economic adviser, Larry Kudlow, claimed that the coronavirus “is contained” in the United States. There were only 75 confirmed cases in the United States at that time.

Today there are 1,629 confirmed cases.

Now that is what I call contained! The Trump administration is obviously doing an excellent job. We should be grateful that we have such a diligent and hard working POTUS!


All hail Donald Trump; a.k.a. Donald Drumpf, a.k.a. Lord Dampnut, a.k.a. Dumbnut, a.k.a. Donnie Trumpelstiltskin, a.k.a. Donald tRUMP; our most, or perhaps least, honored (not my) POTUS and our great Bloviator in Chief!