this post was submitted on 17 May 2024
12 points (92.9% liked)

Experienced Devs

3954 readers
1 users here now

A community for discussion amongst professional software developers.

Posts should be relevant to those well into their careers.

For those looking to break into the industry, are hustling for their first job, or have just started their career and are looking for advice, check out:

founded 1 year ago
MODERATORS
snowe
jmk1ng
drewsiferr
12
Is there a "markup language" to describe a debugging session? (sh.itjust.works)
submitted 5 months ago by [email protected] to c/experienced_devs
10 comments fedilink hide all child comments
 

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!

top 10 comments
sorted by: hot top controversial new old
[–] Lodra 4 points 5 months ago (3 children)

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??

[–] [email protected] 3 points 5 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

[–] [email protected] 3 points 5 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.

[–] [email protected] 1 points 5 months ago (1 children)

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.

[–] Lodra 1 points 5 months ago

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!

[–] [email protected] 3 points 5 months ago

I write my notes in org-mode. It's supported in many editors in a basic form, letting you add code snippets etc in an unobtrusive way. Using a well thought out format helps you in the long run.

I use this in Emacs, through which it lets me refer to emails, execute code snippets, attach related files, fetch content on/from remote servers, send off the debug session as an html email, ... Support will depend on your editor but even as raw text it works.

I don't use something specific to make non-code repeatable as you suggest here, but you could embed a test language in an org code block.

The syntax is straight-forward and exports to multiple external formats exist (eg: html).

[–] [email protected] 2 points 5 months ago

I am a fan of structurizer and the C4 model in general.

I would use a single .dsl file and add the relationships and entities as you discover them. You can apply tags , and then write filtered views to only show specific tags for sub systems or workflows that a user will follow.

you can pair this with markdown/text notes that reference the png files of the views that structurizer will output.

[–] [email protected] 1 points 5 months ago* (last edited 5 months ago)

You should take a look at Mermaid.

Edit: words are hard.

[–] [email protected] 1 points 5 months ago

May not exactly what you're looking for, but jupyter is excellent for documenting a session and you can make it works with C++:

https://blog.jupyter.org/interactive-workflows-for-c-with-jupyter-fe9b54227d92

[–] [email protected] 1 points 5 months ago

Asciidoctor?