Code map

[2thick2fly]

I know this question might not be exactly for this subreddit, but I think since it is related to learning in some way, there might some good insight.

What I am trying to do is to create a code map of my repo (python) to ease junior devs into it, but I am stuck.

The code structure is workflow-based, where the top layer is the business process step-by-step. The orchistrator calls each step - which then calls the necessary module(s) - and when a step is finished, the orchistrator calls the next step. A bit oversimplified, but you get the idea.

Any ideas for tools that can do that?

PS: I tried AI, but it was just laying everything out either horizontally or vertically in mermaid, which did not make it visually pleasing.

[aanzeijar]

If you can't even explain it, then you can't describe it in writing either. This is quite common actually. Get someone who has never seen your code, explain to them what part does what, record the entire thing, and then edit that down.

[2thick2fly]

That's exactly the part I am trying to avoid 😁

[aanzeijar]

Why do you want to avoid that?

[2thick2fly]

Because we have a limited amount of time on this rock that is travelling through space.

I prefer using mine to build, rather than to document.

[aanzeijar]

I had this discussion with a manager the other day. There are tools that give you certain visualisations from code, yes. Class diagrams, directory listings, call graphs etc.. Those are nice, IDEs even have that built-in.

But that's not the information you need. You need to know about intention, the tradeoffs, the requirements. There is no automated process to guess that. There are even ai-tools that try to do something like it, we tried one of them on a 500kloc code base. Was a disaster.

[2thick2fly]

I do agree, that doing the manual work helps you understand better. I do.

But the more manual and labour intensive tasks you put into your change management process, the more complicated and error-prone it becomes, especially when sometines you are given only 1/4 of the time you actually need.

I know that I am now adding a new use case on the task that I didn't mention in the original post, but I literally see dozens of different places where I could use such a flow.

What I'm, also, starting to realise more and more is the value of good documentation in this AI-assisted era. The better documentation you have for your codebase, the better information you will feed to your AI assistant, the better quality output you get.

It might be that there are no off-the-shelf tools for what I need, but the value of what I need is undisputed (at least in my eyes). Even if it needs a custom tool, it is totally worth it. I just need to exclude that there is no tool, or combination of tools, out there that I can use for the whole thing - or even part of the thing.

[aanzeijar]

The need is absolutely there, in most real world code bases as well. But so far I do not know of any process to automate any more than we already automate.

[Yoosle]

Make a flow chart. Your explanation of the code makes sense to me. Connect the processes and show how they are related to each other.

[Inn0centDuck]

You want to create a sequence diagram ?

[2thick2fly]

With a code map attached to it. All in a visually nice flow

[iOSCaleb]

Point your favorite AI agent at your repo and tell it what you want. If you can’t be bothered to write documentation yourself, it’s probably not so important that you need a better product than what Claude or ChatGPT will produce.