I want to document my debugging sessions in a text file but I don’t know if anyone did this before.
I came up with this kind of “language” that is a mix between Markdown and C++, but I still wonder if something equivalent exists already.
// When you click on the button
# [click button]
- A::f()
// - ... other method calls, don't document if you don't need to
# A::f()
// "..." for "parameters" where you don't need the details
- Stuff::g(...)
- Stuff::h(...)
// <Class> is a fake template thing to show the possible types of an object
# <SubStuffA | SubStuffB> Stuff::g(...)
- Stuff::g() {} // empty but I use v/=> for virtual call
v/=> SubStuffA::g()
v/=> SubStuffB::g()
# SubStuffA::g()
# SubStuffB::g()
# Stuff::h(...)
I document methods in the order of appearance in the code.
If you have any good idea about a reliable way to document a list of function calls, I’m interested!
not OP but I’d love something like this for a few reasons.
Sometimes I’m debugging really complicated things and it gets hard to keep track of the info I’ve captured and what I’ve learned, and sometimes you want to recheck some earlier assumption or you learn something new and want to look through older data captured to see if it aligns with newer understandings
Or it’s a long standing thing and need to step away and come back and refresh your memory of the current understanding. And especially when others might also be working on the same problem and you want to collaborate better.
Though I am SRE and thinking of debugging issues in overall systems spanning multiple codebases, hosts, and networks. not just specific bugs in a single codebase like I think OP is doing. So I’m also curious if any tool would actually fit both use cases or if being perfect for one would make it not useful for the other.
For debugging across disparate app, hosts, etc.,x I think the best current option is spans and traces. If you aren’t already familiar, look into general observability, logs/metrics/traces, and definitely opentelemetry!