Debug It! by Paul Butcher

These are excerpts from the book. These are the summary from end of each of the chapter.

Chapter 1 - A Method in Madness

• Make sure to do the following:
• Work out why the software is behaving unexpectedly.
• Fix the problem.
• Avoid breaking anything else.
• Maintain or improve overall quality.
• Ensure that the same problem does not occur elsewhere and cannot occur again.

• Leverage your software’s ability to show you what’s happening.
• Work on only one problem at a time.
• Make sure that you know exactly what you’re looking for:
• What is happening?
• What should be happening?
• • Check simple things first.

Chapter 2 - Reproduce

• Find a reproduction before doing anything else.
• Ensure that you’re running the same version as the bug was reported against.
• Duplicate the environment that the bug was reported in.
• Determine the input necessary to reproduce the bug by:
• Inference
• Recording appropriate inputs via logging
• Ensure that your reproduction is both reliable and convenient through iterative refinement:
• Reduce the number of steps, amount of data, or time required.
• Remove nondeterminism
• Automate.

Chapter 3 - Diagnose

• Construct hypotheses, and test them with experiments.
• Make sure you understand what your experiments are going to tell you.
• Make only one change at a time.
• Keep a record of what you’ve tried.
• Ignore nothing.
• When things aren’t going well:
• If the changes you’re making don’t seem to be having an effect, you’re not changing what you think you are.
• Validate your assumptions.
• Are you facing multiple interacting causes or a changing underlying system?
• Validate your diagnosis.

Chapter 4 - Fix

• Bug fixing involves three goals:
• Fix the problem.
• Avoid introducing regressions.
• Maintain or improve overall quality (readability, architecture, test coverage, and so on) of the code.
• Start from a clean source tree.
• Ensure that the tests pass before making any changes.
• Work out how you’re going to test your fix before making changes.
• Fix the cause, not the symptoms.
• Refactor, but never at the same time as modifying functionality.
• One logical change, one check-in.

Chapter 5 - Reflect

“The six stages of debugging” and reads as follows:

1. That can’t happen.
2. That doesn’t happen on my machine.
3. That shouldn’t happen.
4. Why is that happening?
5. Oh, I see.
6. How did that ever work?

• Take the time to perform a root cause analysis:
• At what point in your process did the error arise?
• What went wrong?
• Ensure that the same problem can’t happen again:
• Automatically check for problems.
• Refactor code to remove the opportunity for incorrect usage.
• Talk to your colleagues, and modify your process if appropriate.
• Close the loop with other stakeholders.

Chapter 6 - Discovering that you have a problem

• Make the most of your bug-tracking system:
• Pick one at an appropriate level of complexity for your particular situation.
• Make it directly available to your users.
• Automate environment and configuration reporting to ensure accurate reports.
• Aim for bug reports that are the following:
• Specific
• Unambiguous
• Detailed
• Minimal
• Unique
• When working with users, do the following:
• Streamline the bug-reporting process as much as possible.
• Communication is key—be patient and imagine yourself in the user’s shoes.
• Foster a good relationship with customer support and QA so you can leverage their support during bug fixing.

Chapter 7 - Pragmatic Zero Tolerance

• Detect bugs as early as possible, and fix them as soon as they come to light.
• Act as though bug-free software was an attainable goal, but temper perfectionism with pragmatism.
• If you find yourself faced with a poor quality codebase, do the following:
• Recognize there is no silver bullet.
• Make sure that the basics are in place first.
• Separate clean code from unclean, and keep it clean.
• Use bug triage to keep on top of your bug database.
• Incrementally clean up bad code by adding tests and refactoring.

Chapter 8 - Special Cases

• When patching an existing release, concentrate on reducing risk.
• Keep on the lookout for compatibility implications when fixing bugs.
• Ensure that you have completely closed any timing windows, not just decreased their size.
• When faced with a heisenbug, minimize the side effects of collecting information.
• Fixing performance bugs always starts with an accurate profile.
• Even the most restricted communication channel can be enough to extract the information you need.
• Suspect your own, ahead of third-party, code.

Chapter 9 - The Ideal Debugging Environment

• Automate your tests, ensuring that they do the following:
• Unambiguously pass or fail
• Are self-contained
• Can be executed with a single click
• Provide comprehensive coverage
• Use branches in source control sparingly.
• Automate your build process:
• Build and test the software every time it changes.
• Integrate static analysis into every build.

Chapter 10 - Teach your Software to Debug Itself

• Use assertions to do the following:
• Both document and automatically validate your assumptions
• Ensure that your software, although robust in production, is fragile during debugging
• Create a debug build that
• Is compiled with debug-friendly compiler options
• Allows key subsystems to be replaced by debugging equivalents
• Builds in control that will prove useful during diagnosis
• Detect systemic problems, such as resource leaks and exception handling issues, preemptively.

Chapter 11 - Anti Patterns

• Keep on top of your bug database to ensure that it accurately reflects your true priorities.
• The polluter pays—don’t allow anyone to move onto a new task until they’ve completely finished their current one. If bugs come to light in their work, they fix them.
• Make a single team responsible for a product from its initial concept through deployment and beyond.
• Firefighting will never fix a quality problem. Take the time to identify and fix the root cause.
• Avoid “big bang” rewrites.
• Ensure that your code ownership strategy is clear.
• Treat anything you don’t understand as a bug.