[AndyPatterson]

The problem facing these tools is a catch-22 really - diagrams are useful when understanding big messy codebases but big messy codebases are hard to visualise.

For instance, I frequently build small paper diagrams of different code paths through a component and nearly always find leaky abstractions, mixed layers of abstractions, weird cyclical dependencies, etc. etc. and there really is no clear way to diagram this. Instead, you sort of have to make judgements and assumptions to make the diagram concise and understandable; the sort of decisions that machines just aren't that good at.

On the other side, when code is simple and easy to follow then the pay off of building a diagram just isn't there.

[altgeek]

"... make the diagram concise and understandable; the sort of decisions that machines just aren't that good at. ..."

Exactly. I've found that there is no perfect tool and I'm closing in on 40 years of writing software. I use a blend of UML, IE (James Martin's Information Engineering), etc. Anything that makes it "easy-to-grok". Draw.io generally does what I want it to do; there is no feedback loop back to the codebase. It's really just to help onboard new helping hands.

[lurker137]

I'm starting to see all the problems with static diagram creation. I still think there can be more work in this area, maybe a full dynamic solution separate from the IDE that just helps you navigate the maze and make your own diagrams. With all the work that's been going into making developers' lives easier surely someone could focus on the exploring codebase part.

[etimberg]

Paper and pencil is definitely the way to go. If i make something that turns out to be useful I’ll make a digital version after.