Debugging Microsoft Windows Applications by John Robbins

From Barnes & Noble

The Barnes & Noble Review
Debugging: it's the aspect of development most likely to keep you up all night, screaming at your computer—and your colleagues. What's worse, when you think about your development cycle, it's not unusual for debugging and related activities to eat up half your time. If you develop for Windows, there's a new alternative to more coffee and Jolt Cola: Debugging Applications, by John Robbins.

Robbins writes the Bugslayer column for Microsoft Systems Journal, and you won't find a more dedicated, committed expert on the subject. As he puts it, his new book takes a holistic approach to debugging. "I don't consider debugging as a separate step but as an integral part of the entire product cycle... you need to start debugging in the requirements phase and continue through to the final release to manufacturing." That's what this book shows you how to do.

Robbins starts by presenting "the gestalt of debugging"—defining the different types of bugs that exist, and presenting an approach and process to debugging that many great developers have evolved on their own. Robbins also offers specific, Windows-focused techniques for proactively debugging as you write your code—and for keeping you out of your debugger by helping you write cleaner, less buggy code up-front.

Next, he introduces "power debugging" techniques that make the most of your debugger—whichever one you're using, in Visual C++ or Visual Basic. Most developers don't use a fraction of the power of their debuggers—after youreadRobbins, you won't be one of them.

In Part III—fully half of the book—Robbins presents solutions to the debugging problems you're most likely to encounter in Windows applications—from tracking down deadlocks in multithreaded programs to automatically testing user interfaces, debugging Windows 2000 services and DLLs that load into services, and more. Throughout the book, you'll also find great sidebars and war stories—many from his experience at NuMega, one of the world's leading providers of debugging tools. Once you read this book, you'll never look at debugging the same way again—and you certainly won't spend as much time doing it!

From the Publisher

Amid a booming market for third-party software debugging tools-evidence that bugs and defects are a pernicious fact of everyday programming life-there exists no single guidebook that adequately addresses the topic of debugging as a programming discipline. But with the upcoming publication of DEBUGGING MICROSOFT WINDOWS APPLICATIONS, developers finally get the practical, Windows-focused reference they need for finding and correcting costly coding errors. The book takes a holistic approach to debugging-redefining "bugs" not just in terms of crashes and high- profile calamities, but including everything from user interface problems and performance issues to incomprehensible product manuals.

The first section introduces the "Zen of Debugging," outlining what developers need to know both before and during product development. Section two demonstrates how to maximize the vastly under-utilized built-in debugging capabilities in the Visual Studior product family. The last section of the book steps readers through specific debugging situations and their solutions, covering such topics as multithreaded debugging, crash handlers, and automated regression testing. Throughout, the book focuses on practical, tested techniques-ready for work-in the tradition of the award-winning Microsoft Pressr Best Practices series.

Product Details

• Table of Contents
• Forewords & Introductions
• Read an Excerpt

Table of Contents

Forewords & Introductions

• Explain who the heck John Robbins is

• Tell you why you want to read this book

• Tell some good stories about John Robbins

My first encounter with John was on a CompuServe forum. He was working on a homebrew debugger and had posted a question about the Microsoft Win32 Debugging API. In jest, he added that if he finished his debugger, maybe he could get a job at NuMega. I noticed the message and replied to him. I also mentioned that, incidentally, NuMega was looking for people (debugger nerds being hard to come by).

So began John's roller-coaster ride at NuMega. John showed up for his interview wearing a suit (probably his only one) and carrying a stack of neatly formatted floppies that contained his sample code, which was his completed debugger. During the interview, one of NuMega's owners fell asleep. (Or so John thought. The owner was actually focusing very intently.) John figured his chance at a job was gone right there, but in fact, he impressed everyone. A few months after John had been hired, he noticed that I was using one of his sample code disks as a coffee coaster. The truth was, I knew just from talking to him that John was hardcore about debugging, and I didn'tneed to check out the code.

In those days, NuMega was pretty small and was completely focused on getting cutting-edge debugging tools into developers' hands. John paid his dues in this crusade. He was so anxious to start work at NuMega that he moved from Virginia to New Hampshire almost immediately and rented one of the first places he found, a small house behind a fire station. Every time the fire station's doors roared open, John's PC lost power. At work, his first assignment was to write BugBench, a utility that demonstrated every error that BoundsChecker could catch. During that time, we rightfully called John the world's buggiest programmer.

A few months later, John's PC began freezing for roughly 10 seconds every hour or so, Despite his sharp words with the network administrator, no solution was forthcoming. Finally, John got his hands on a very early version of SoftICE for Windows NT (NuMega's kernel debugger). It didn't take long for John to figure out that another engineer had placed a Windows NT service on John's machine that counted to 175 million at random intervals using a time-critical thread. Try as he might, John was never able to top that prank.

A big part of NuMega in those days was sending engineers to trade shows. John's outgoing personality made him a natural target for the marketing folks, who were eager to include him in the booth presentations. One of the more, ahem, lame concepts involved a skit that had John starring as "a researcher at the Center for Bug Control in Atlanta." John wanted no part of this escapade, so he and another engineer came up with a completely different concept, an idea that became the genesis of the world-famous "Senior Boy and Junior Boy" skit. John was "Senior Boy," which became one of many nicknames John acquired at NuMega. I'll leave the origination of "Sporkie Boy" to your imagination.

As a footnote to that trade show, it was also where John learned what's really inside those stress-relieving balloons seemingly filled with sand. In this particular instance, the filling appeared to be tiny fragments of walnut shells. As John held the balloon over his head, he managed to puncture it, covering both of us-nay, the entire hotel room-in walnut shells. The shells even managed to find their way into the blankets and sheets of the beds.

The first half of John's time at NuMega was spent working on all aspects of BoundsChecker. His duties included developing the debugger loop, writing API validation stubs, fixing symbol table bugs, tweaking with the reference-counting algorithm for COM interfaces, and extending the code for streaming program trace information to disk. All in the same day! Debugging a debugging tool, especially one that takes liberties with the operating system, provides plenty of opportunity to hone your debugging skills.

Often John and I weren't able to use a debugger on the tough problems. One problem in particular I remember was when I ran BoundsChecker on Microsoft Visual SourceSafe the night before an important beta. It seemed to run fine, but a few minutes latey, another engineer noticed that the file dates in Visual Sourcesafe were something like "@@1?70." Regular backups weren't yet a part of our engineering process, so I ended up nearly completely destroying the version control database that held the only copy of the source code. Needless to say, the entire company was out for my hide, but John and I knuckled down and discovered that Visual SourceSafe was using some legacy MS-DOS code that trashed our file handles.

You might be wondering, "Why all these stories?" My point is that John is no academic or abstract theorist. John has walked the walk (and definitely likes to talk the talk). John and I frequently lament the fact that so many programming books are written by people who have little or no commercial development experience and who don't write programs that exceed 100 lines. John was a lead developer on several award-winning products. When he writes, he's conveying information learned from his hard-won experiences.

When John decides to do something, he does it whole hog. He will wrestle with a subject until he has it completely pinned. "I couldn't figure it out" isn't in John's vocabulary. Before John began his writing career, he offered to help me with a few functions for a Microsoft Systems Journal (MSJ) column I was working on. I think he spent more time on the code than I did. Because we both now write columns for MSJ, we regularly swap stories on the horrors we encounter while writing the code that accompanies our columns. On many occasions, his descriptions of how far he went to chase down a problem have left me slack-jawed.

Writing a book requires more than just knowledge of the subject matter. It also requires a desire to communicate this knowledge effectively to the reader. I noticed John's easy way with words in his very first article. I still consider it a treat to read anything by John Robbins. It's a pleasure to read something when I know the author truly understands the subject matter, has a passion for communicating it, and doesn't make it sound more complicated than it needs to.

John's enthusiasm for writing extends beyond just his articles, his columns, and this book. John leaves his stamp in just about any code he writes, as this excerpt from a classic e-mail I received at work shows:

What is with all this "DISCUSSION" crap John litters the core with? Every damn function header is prefaced with a complete chapter on the sociological implications of using the routine and how planets may misalign if you use them improperly - last month's MSJ was nearly a friggin book, most of it filled with all of this "DISCUSSION" crap - he wrote almost a book in and of itself for his "Form Load" handler. Is the man an author or an engineer? Jeez...

As you'll see in this book, the answer is both!

Debugging is a subject that's shrouded in mystery, and in many ways it's an oral tradition. Good texts are sorely needed. The few books available focus mostly on sanitized situations and don't get into the swampy details that effective Windows debugging often entails. From time to time, publishers have approached me about writing a book on debugging, and I've always declined. It's not that I don't know enough about debugging. Rather, I find it difficult to quantify my gut-level debugging knowledge into something that can be put on paper. John doesn't have this problem.

From my perspective, effective debugging is pretty simple at a high level. I always come back to two tenets:

• Know what's supposed to be happening

• Know how to use your tools to see what's really happening

If you have these two things nailed, debugging is usually straightforward. The problem is, both of the above items aren't so easy to pull off. When I say "Know what's supposed to be happening," I don't expect your knowledge to stop at your source code. You have to be able to see both the big picture and the microscopic details. What did the compiler mutate your code into? What happens inside that API call? If you can't answer these questions, you're flying blind.

I'm not saying that to debug you need to trace through every instruction. Rather, when the need arises, you should be able to keep breaking the problem into smaller and smaller pieces-something John recommends in Chapter 1 of this book. You might also have to dig into components that you don't control to find the cause of a crash. Eventually, you'll find the answer if you go deep enough into the bits. A lot of tracking down bugs requires you to know the intricacies of your language, operating system, and CPU-another topic John covers in Chapter 1. The chapter on the minimum amount of x86 assembly language you should know (Chapter 6) will be an invaluable resource for you.

Likewise, knowing how to use your tools effectively is critical. Debugging tools have become fairly sophisticated, and many developers never get (or don't take) the opportunity to become familiar with the full range of their tools' capabilities. I'm reminded of a friend who had a brilliant young graphics programmer working for him. When the prodigy's code crashed one day, he had no idea that his debugger could show him a call stack.

Too many developers learn just enough debugging skills to get them out of their current jam. Often, users overlook great features of debugging tools because the situation in which to use them isn't put into the proper context. Reading through documentation, feature by feature, gets boring, and you learn only the most basic information. John's chapters on power debugging in the Microsoft Visual C++ and Microsoft Visual Basic debuggers (chapters 5 through 7) take you far past the tedium of "step, step, step. Inspect. Step, step, step..."

When I say debugging is an oral tradition, I mean that most people learn a new debugging skill or technique only when they hear about someone else using it to solve a problem. When you watch a master at work with good debugging tools, you can learn 10 times as "much in 30 minutes as you would in a day of reading the documentation by yourself. John is. just such a master of debugging. He knows the strengths and weaknesses of all the tools he uses. He also invests his time up front to write great diagnostic code that more than pays for itself later. You can do the same for yourself by making debugging a skill that you continually enhance rather than a chore. This book is chock full of nuggets of John's debugging gold to help speed you on your way.

Matt Pietrek
Hollis, New Hampshire
December 1999

Read an Excerpt

Chapter 2. Getting Started Debugging

All the ideas presented here and in Chapter 3 come from my experience shipping real-world software products, and I can't imagine developing without these tools and techniques. I've learned some lessons the hard way, and I hope to save you time and pain by sharing with you what these lessons have taught me. You might think that some of these ideas don't apply to you because you're on a two-person or threeperson team. Don't worry, they do. Even when I'm on a team of one, I still approach a project in the same way. I've worked on projects of every size you can think of, so I know the recommendations I make scale from the tiniest to the largest teams.

Track Changes Until You Throw Away The Project

Version control and bug tracking systems are two of the most important infrastructure tools you have because they give you the history of your project. Although the developers might say they can keep everything in their heads, the company needs to have some record of what's been accomplished on the project in case the entire development team wins the lottery and everyone quits the next day. Because most teams don't adequately maintain their requirements and design documents throughout the life of a project, the only real documentation becomes the audit trail in the version control and bug tracking systems.

I hope I'm preaching to the converted. Unfortunately, I keep running into teams that haven't yet started using these tools. As someone interested in history, I feel you have to know where you've been to know where you're going. Putting these two tools to use is the only sure way to learn that lesson. By monitoring the outstanding bugs and bug fix rates in the bug tracking system, you can better predict when your product will be ready to ship. With the version control system, you'll get an idea of your "code churn," the volume of changes, so that you can see how much additional testing needs to be done. Additionally, these tools are the only effective way to judge whether you're getting any results from changes you implement in your development cycle.

When you bring a new developer to your team, these tools can pay for themselves in a single day. When the new developer starts, have her sit down with the version control and bug tracking software and begin working her way through the changes. Good design documents are ideal, but if they aren't available, the version control and bug tracking systems at least provide a record of the code evolution and highlight any trouble areas.

I'm talking about these two tools in the same breath because they are inseparable. The bug tracking system captures all the events that might have driven changes to your master sources. The version control system captures every change. Ideally, you want to maintain the relationship between reported problems and actual changes in the master sources. By correlating the relationship, you can see your cause and effect for bug fixes. If you don't track the relationship, you're left wondering why certain changes to the code occurred. Invariably, in later versions of the product, you have to find the developer who made the change and hope he or she remembers the reason for the change.

Some products are integrated and automatically track the relationship of the master source change to the bug report, but if your current systems don't, you'll need to maintain the relationship manually. You can track the relationship by including the bug number in the comments that describe the fix. When you check the file back into version control, you'll need to identify the bug number you're fixing in the checkin comment for the file.

Version Control Systems

The version control system isn't just for your project's master sources. Anything and everything related to the project-including all test plans, automated tests, the help system, and design documents-needs to go into the version control system. Some companies even include the build tools (that is, the compiler, linker, include files, and libraries), which allows them to completely re-create the shipped version of their product. If you have any question about whether something should go in version control, ask yourself whether maintenance programmers could use the information in a couple of years. If you think they could, that information belongs in the version control system.

Controlling Changes

Tracking change is vital; however, having a good bug tracking system in place doesn't mean that developers should be allowed to make wholesale changes to the master sources whenever they want. Such carte blanche would make all the tracking pointless. The idea is to control the changes during development, restricting certain types of changes to certain stages of the project so that you can have an idea of the state of the master sources on a day-to-day basis. The best scheme I've heard of for controlling changes comes from my friend Steve Munyan, and he calls it "Green, Yellow, and Red Times." In Green Time, anyone can check in anything to the master sources. The earliest parts of the project are usually fully in Green Time because at this point the team is working on new features.

Yellow Time is when the product is in a bug fix phase or nearing a code freeze. The only code changes allowed are for bug fixes-and only bug fixes. No near features or other changes are permitted. Before a developer can check in a bug fix, a technical lead or a development manager must approve it. The developer making the bug fix must describe the bug fix he's making and what it affects. In essence, this process is a mini code review for every single bug fix. On some teams I've been on, the product was in Yellow Time from day one because the team liked the code review aspects of this stage. We did loosen the approval requirements so that any other developer could approve changes. The interesting outcome was that because of the constant code reviews the developers caught many bugs before they checked the code into the master sources.

Red Time occurs when you're in a code freeze or near a key milestone and all code changes require the product manager's approval. When I was a product manager, I even went to the extent of changing the permissions in the version control system so that the team had read-only access. I took this step mainly because I understood what the developers were thinking. "This is just a little change; it will fix this bug, and it won't hurt anything else." The developers' intentions were good, but that one little change could mean that the entire team would have to restart the test plan from the beginning.

The product manager must strictly enforce Red Time. If the product has a reproducible crash or data corruption, the decision to make the change is essentially...