My Debugging Process
Here is the process I go through when trying to debug a tricky coding problem.
First, I run a private personal blog which I use for debugging and taking coding notes. You can consider this your coding journal, and whatever tool works for you.
I find something digital works better, since you can use HTML allowing you to link to various things, upload images, and drop in snippets of code. A blog works well because it allows for adding comments as you troubleshoot.
I'm deeply involved in WordPress, so I use WP and the P2 theme, which is a simple front-end editor and comments. A quick and easy way to start is setup a hosted site on WordPress.com. Disclaimer, it is where I work, but it really is easy.
The tool doesn't matter too much, but having a tool and writing out the problem is the key.
Debug Template
When encountering a bug that I know might be tricky and require longer than usual to debug and solve, I'll start a new post using the the following template which is basically the scientific method:
- Problem
- Info
- Hypothesis
- Experiment
- Results
- Conclusion
First, I'll write out the problem as reported, linking to any issues open, test cases that duplicate it, or any other information needed to describe the problem. I try to gather as much info about the problem here, without trying to solve it yet.
Second, I'll start to investigate and collect up some info, for example recent changes, links to code blocks that might be effected, documentation about the issue, or anything else that I will probably refer back to as I debug.
I'll create a post with the above two items as the body of the post.
I'll then start a comment which will cover steps 3-5. My comment will state a hypothesis of what I think is causing the bug. I can then nest comments under that hypothesis, with my experiment and then results.
If that hypothesis fails, I'll start a new comment with a new hypothesis, experiment, and then results.
I usually don't write any code until I've devised what my experiment is going to be, often times what happens as I'm writing out the hypothesis, I'll solve the problem. The act of writing out the problem, collecting info, and then writing out the hypothesis usually triggers the thinking needed to solve.
If I just start jumping in and writing code, testing and guessing, I get into the weeds quickly and it becomes more confusing, I find stopping and thinking about the problem and the act of writing it down helps me work my way through.
It is an example of rubber ducking, just the act of talking to someone else often solves the problem without requiring any real intervention by them.
If I have to write down the problem, I first have to understand the problem. If I have to write down my hypothesis on how to solve the problem, I have to understand what I'm actually thinking.
So its not uncommon that my coding notes have The Problem, and written Hypothesis and then jumps to a conclusion that it is fixed with a link to the fix. This is fine with me, because the goal is to solve the issue, I'm not too worried about my coding journal completely following the template or not.
There are also Problems which have multiple hypothesis, tests, and failed results. In these cases, it is helpful to be able to go back and see the steps written out, what has failed and why.
It is particularly useful when you share with others helping you debug. They can read how I am thinking, what I have tried, and helps get to a solution quicker.
Also, when bugs come back 3 months later, which they always do. You can refer to your notes and see what caused the problem last time, have info and links available which will give you a head start solving the issue again.
Summary
So give it a try and start a coding journal to help yourself debug problems. Force yourself to write down the problem and your thoughts, and often times that is all you need.
Side note: I've also been playing with running a custom WP theme built for code notes. It is based on the Draft.js editor and a single-page React app. You're welcome to try it out, but I would consider it quite experimental at this point.