Debug your code like a doctor

Designing and maintaining good software is a never-ending struggle against complexity. The code paths and components of any sufficiently large application can quickly grow into a dizzying combinatorial explosion.

Not simple at all.

Single-server web applications become distributed systems when deployed on platforms like Heroku and AWS. Modern browsers blur the line between client and server. Simple programs become complex coordination problems when they run on multiple CPU cores. While practices like test-driven development and guidance like SOLID principles can help us model problems and simplify solutions, most software applications are complex systems where components interact and combine in unexpected ways.

When unexpected things happen in software systems, the consequences can be serious. Fortunately, software developers can learn from another, older discipline to help them care for, maintain, and debug complex systems: medicine.

[[136924]]

A differential diagnosis is a systematic approach that doctors use to match sets of symptoms to their possible causes. A good differential diagnosis involves the following 4 steps:

1. List all symptoms observed.
2. List possible causes.
3. Rank these causes in order of importance.
4. Tests are performed in order of priority to rule out causes.

Although the above four steps are organized for doctors, we can also think like a doctor and find and eliminate software defects in a powerful way. Break down the diagnostic process into single-purpose steps to ensure that each step receives due attention. Prioritize to ensure that you focus on the key points of the inspection and make pragmatic interventions. Then test and eliminate assumptions to ensure rigorous debugging.

Whiteboard is a good thing

When an error occurs, most of us jump right into investigating the most likely cause without a second thought. With backward tracing and a little background knowledge, human nature tends to be opportunistic. But good diagnosis starts with a list of symptoms, not causes. Write down all the symptoms you can observe, whether it's exception handling, error codes, or even just unusual behavior. You can use a text editor or a whiteboard, but it's important that you take notes at every step in the diagnostic process. Separating observations from hypotheses helps ensure that you don't rule out or ignore potential causes. And most of the time, listing more symptoms will narrow the possibilities and prevent you from wasting time testing incorrect hypotheses.

Now that you have a list of symptoms, you can start thinking about the causes.

Zebra and horse

"When you hear hoofbeats, look for horses, not zebras."

You are more likely to find a bug in your code in an application than in a web framework, and it is easier to find a bug in a web framework than in an operating system. Of course it is a good idea to have someone review your code, but the fact is that most bugs are extremely boring to review. So before you start thinking about advancing to more complex problems, let's give the simplest explanation first.

Then again, just as the same symptom may be caused by completely different causes, we should write down all the relevant causes we can think of. Just as we originally described the symptoms directly as "what" and then distinguished them with "how", the purpose of the brainstorming explanation method is to distinguish "how" with "how likely". Capture any seemingly reasonable points to facilitate economical analysis.

The most important thing is not to cause any harm

Differential diagnosis differs from other deductive methods because doctors must constantly assess risk and weigh the impact on the patient's life. Of course, if there is a bug in our product, it is not as serious as the doctor's responsibility for life, but there are real and painful costs to stop repairing. Just like life-threatening disease events require immediate intervention, serious bugs may require crude and simple fixes such as rollback and restart. Prioritize the hypotheses, then consider the trade-offs and make a judgment call whether to start testing the hypothesis or intervene immediately.

Prepare the chart

Just as patients have charts of their hospital records and other background information, you may need charts for your software systems. Gather information from logs and error reporting systems to inform your analysis. As for system metrics and tracking errors, think of them as sensible preventative medicine.

If your patient is not in serious danger, start with a hypothetical-deductive approach. Start with the highest-priority hypotheses you define and prove them wrong one by one. While supporting evidence may sometimes help you find the bug, failed tests drive the deductive process. It may seem counterintuitive at first, but the test-and-eliminate hypothesis strategy is the fastest way to trace a bug back to its cause. In many cases, a few simple tests can eliminate several hypotheses at once. Of course, there are also times when you have to perform more tests to disprove a hypothesis.

Laboratory work

Unlike the medical world, which is unacceptable, you can always clone software applications and perform horrific human experiments if you want. If you have enough information to trigger the bug you want to diagnose, you can replicate it in a controlled environment, such as a staging server with a backup of the latest database. As you eliminate causes, collect new data, and refine your hypotheses, clues to the true cause of your bug will become clearer.

Thinking clearly about complex systems requires care and focus. Using a structured diagnostic process to guide your inspection can save time and frustration. Most importantly, it works. The next time you are stuck on a bug, try putting away the keyboard, writing the steps step by step on a whiteboard, and debugging like a doctor.

Translation link: http://www.codeceo.com/article/debug-like-doctor.html
Original English text: Debug like a doctor
Translated by: Coder.net – Wang Guofeng