21st Century C

Chapter 2. Debug, Test, Document

Crawling  Over your window  You think I’m confused,  I’m waiting ...  To complete my current ruse.

—Wire, “I Am the Fly”

This chapter will cover tools for debugging, testing, and documenting your writing—the essentials to take your writing from a potentially useful set of scripts to something you and others can rely on.

Because C gives you the freedom to do idiotic things with memory, debugging means both the quotidian problem of checking logic (with gdb) and the more technical problem of checking for memory misallocations and leaks (with Valgrind). On the documentation side, this chapter covers one tool at the interface level (Doxygen) and another that helps you document and develop every step of the program (CWEB).

The chapter also gives a quick introduction to the test harness, which will allow you to quickly write lots of tests for your code, and concludes with some considerations about error reporting and handling input or user errors.

Using a Debugger

The first tip about the debugger is simple and brief:

Use a debugger, always.

Some of you will find this to be not much of a tip, because who possibly wouldn’t use a debugger? But many users come from languages that throw up a backtrace at the first sign of trouble, and didn’t get to the part where their C textbook introduces the debugger (it is often in the other topics segment, somewhere around Chapter 15). So now we’re all on the same page: the debugger exists.

I’ve found other people who worry that ...