Some bugs are hard. Doubly so in unfamiliar code. You end up going down multiple paths, trying out any number of changes, adding tracing and consistency-checking code to verify your assumptions. You end up manually annotating huge traces for a single test case, just to figure out which way is up (this is in the context of code generation, but I think it applies more widely). You start noting things down just so that you don’t end up retracing your steps (… too often).
You occasionally engage in breadth-first search, exploring a number of debugging approaches, just so you can get a feel for the RoI on each path. You may have already made significant code changes in your pursuit of a fix, only to realize that this is a dead-end and some of your traces and/or assumptions are now invalid.
Something looked like an inconsistency but, after a lot of time spent understanding the code, turns out to be OK. You still value what you learned about the code though.
Question: how do you keep notes in this kind of debug session that can last days (if not weeks)?
In practice, I tend to keep a huge org-mode file for such issues, with different sections for annotated traces, annotated artifacts, TODO items for thins to look into, open questions re: the thing I’ve been looking into. However, given the above, my notes end up expanding all over the place, to the point that I have started adding timestamps (when I remember…) so I can better reconstruct where I left off the previous day.
Can anyone suggest a lightweight strategy for keeping less chaotic debugging notes?
you could write a small tool to append to a log file of your observations. maybe it’s an extension for vscode or whatever you’re using to append to a notes file similar to an org file. maybe it notes where you are in the source code with filename line number and sha of the commit(though that is probably not super useful since your code may differ from what was last committed) and whatever note you have.
could have the tool have a concept of “working on” that starts a new note under the working on name and appends to that. all could be under the project directory under
sounds like a useful tool actually.
I recommend Andreas Zeller’s “Why Programs Fail: A Guide to Systematic Debugging”, in which the author suggests keeping a log, where entries are in the form
(This is an example for a toy program, real examples are more complex)
Combined with algorithmic debugging, it is a really invaluable method for finding bugs
That’s the kind of thing I was looking for! TBH the above sounds somewhat heavy-weight for regular use (especially how hard describing some hypotheses can be, let alone summarizing results), but OTOH there is some unavoidable complexity in debugging and perhaps at some point this kind of overhead becomes negligible?
Thanks for the book recommendation! I’ll try to get my hands on it and use its suggestions as a starting point for further experimentation.
I found this too when I first tried the techniques, but I’ve come to realise that if I can’t write down hypotheses about why the system isn’t working, then this usually means I need to try and understand the system better before I can effectively debug it.
The author considers this too!