Guidelines for Debugging

The following guidelines provide several techniques for debugging code.

Required

  • Learn to use debugging tools.

    You must understand and master debugging tools. For more information, see Debugging in Visual Studio.

  • Know where your symbols are archived.

    Symbols for every product must be archived on symbol servers. You just need to know where to find these servers. For more information, see "How to Use the Microsoft Symbol Server" in the MSDN Library.

  • Study and resolve bugs that hang processes.

    To users, an application that stops responding (hangs) is as bad as a crash. Either way, users lose work and must start over. However, hangs have been thought of as being much harder to study and resolve. That is no longer true for a large percentage of process hangs. Use the latest tools and techniques for solving these problems. For more information, see "How to Troubleshoot Program Faults with Dr. Watson" in the MSDN Library.

  • Know how to debug a minidump.

    Most testers and customers will crash your code without the benefit of an attached debugger. If you cannot reproduce the issue easily then all that you will have is a minidump. Learning to debug by using a minidump is essential. For more information, see "Minidump Files" in the MSDN Library.

  • Know how to recover a corrupted stack.

    Recovering a corrupted stack is complex, but recovering it is essential because so many real-world failures have stacks that seem incomprehensible. For more information, see "Troubleshooting Common Problems with Applications: Debugging in the Real World" in the MSDN Library.

Avoid

  • Assume test will find all the bugs.

    Test will never be able to find all the bugs. It is not possible. Code is too complex. Even if test could find all the bugs, you would never have time to fix all of them. The right thing to do is to design your product so that bugs are not in the product from the start. Save yourself the trouble of fixing them later. You must take responsibility for the quality of your code. The test team just verifies the quality of your code. Do not depend on testers to clean up your mess.

  • Know how to debug multithreaded applications.

    Introducing threads to a program can cause it to fail in new ways. Everything that you do in a single-threaded environment to help debug applications become more important as the number of threads increases. For example, you might not always catch the error at the point it occurs. Usually the error is caught later, possibly in another thread. In these situations, you cannot even walk back up the call stack to find the problem; the error was in another thread, with another stack. Being as proactive as possible will help the debugging process in general.

  • Learn how to do remote debugging.

    Remote debugging occurs when you want to debug a problem that is occurring on another computer while continuing to work from your own computer. Developers frequently do this when a segment of code runs fine on their own computer but crashes on another system. They may want to debug it on the other system remotely, without having to go sit in front of the other computer. For more information, see Remote Debugging Setup.

  • Learn to debug on live servers.

    Debugging procedures are different when you are trying to debug code on a live server that customers are accessing. This is getting more common as more code is written for the Web. For more information, see "Troubleshooting Common Problems with Applications: Debugging in the Real World" in the MSDN Library.

  • Comment all bug fixes.

    When you fix a bug, include in the code a version number, bug ID, and your alias. If someone looks at the code afterward and has a question about the fix, they can contact you for information.

  • Review all bug fixes.

    You should code review all fixes. Get at least one other person to examine your code —a peer review.

  • Verify subtle bug fix before check-in.

    Avoid fixing the same bug twice. Use a build to verify that the fix is correct, especially for subtle bugs.

  • Use a test release document to report all bug fixes.

    Coordinate with test team by documenting all your bug fixes in a test release document (TRD) and sending it to the test team in e-mail.

  • Use Symbol Server to index and archive your product symbols.

    By permitting Symbol Server to index and archive your product symbols, you make debugging from any system, including customer systems, fast and easy.

  • Fix other people’s bugs without letting them know.

    It is a wonderful practice to research and attempt to fix other people’s bugs. You get to know the code better, and you are serving as backup for other people. The only thing that you should not do is check in the fix without letting the owner of that code know about the fix.

  • Resolve a bug as "Not Reproducible" without trying the same version in the same environment.

    You must roll back to the version of the product where the bug was found. Do not assume that if it is not broken on the current version of the product, the bug must have been fixed. That might not be true. The code could have changed so that it just hides the bug now. If you investigate a bug until you see it break, you might actually find the root cause of the problem and fix it so the bug will not occur again on any computer.

See Also

Concepts

Guidelines for Writing Secure Code

Other Resources

Debugging Terminology
Dumps
Common Language Runtime Minidump Tool