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!

  • Lodra@programming.devEnglish
    3·
    4 months ago

    I certainly don’t have an answer for you. Sorry 🙂

    I’m super curious about your motives and goals though. Why do you want to do this??

    • best_username_ever@sh.itjust.worksOP
      3·
      4 months ago

      Why? I got a new job and, for a lot of reasons, it’s the first time I’m really motivated by my coworkers. I want to understand this small but relatively complex codebase, and the bookmarks/breakpoints system is not good when you need to discover a lot of topics in a short amount of time (a few months usually when you get a new job).

      I’m currently fixing bugs, and while it’s going great so far, some bugs are more complex and may require me to understand the whole “flow” of the architecture, but it’s different for each bug. I work in the medical field and I have to juggle with a few bugs at the same time before anything is validated, that’s why I wanted to take notes of what I deemed interesting while debugging.

      Also I often switch branches which explains why breakpoints have to be changed all the time. Breakpoints and Doxygen don’t show in a simple way how the code can go from step 1 to step 2 to step 3.

    • 0x1C3B00DA@fedia.io
      3·
      4 months ago

      I could see walking through a debug session document with a junior dev to guide them on how to debug classes of issues better. Or if they’re running into a bug and ask for your help, you could write out the first few debugging steps and let them take it from there. That might be easier to understand than “I’d check service X and see if it’s processing Y like it should or just passing it on to Z”. Having a defined way to explain how to debug an issue could be useful