Ask HN: Why aren't code diagram generating tools more common?

It would be funny if there was a single explanation, like, “The tool for creating simple visualizations that helps you understand codebases doesn’t exist yet.”

The GitHub repo visualizer was especially useful for me https://githubnext.com/projects/repo-visualization

Speculating based on both writing large systems from scratch, and joining a group where a large confusing system was being used...

Diagrams are sometimes unnecessary overhead early in a project. Sometimes I’ve used them and seen other people use them for initial design planning, especially if management needs to be involved or approve the plans & schedule. But by a year later, the design has grown and changed, and everyone on board is so familiar with the code, but also so pressed for time and feature delivery, that making diagrams doesn’t make sense: nobody involved at this point needs them. Two years later, when the code is getting complicated and slowing down, and you’re onboarding some new people, that’s when it might help to sketch the flow of code.

FWIW, sometimes a good profiling tool will show you and let you explore call stacks, call graphs, execution charts, etc. I often reach for a profiler when I’m new to a codebase. Flame charts are a fave of mine. You can find flame charts in Chrome’s debug tools, or in compiled language profilers like vtune or valgrind. Here’s a decent article on how to use them https://www.brendangregg.com/FlameGraphs/cpuflamegraphs.html

Another issue is that well designed code bases diagram themselves by their module structure, while diagrams for poorly designed code bases may not help understand them at all. When code has too many side effects, or things are poorly or misleadingly named, when class boundaries aren’t well defined or the code has a lot of spaghetti, diagrams might not really help.

IMO two things worth doing are: get a mentor in any new codebase any time you can, and 2) start building your own arsenal of code diagramming tools, rather than wondering why or waiting for others to do it. Demonstrate the value of diagramming code to people around you and see if you can get it to catch on.

I’ve had this need a few times. Just a couple weeks ago I needed to quickly understand the set of package dependencies within a codebase and wrote some scripts that extracted a report as well as a graphviz file. I’ve done that a few times over the years. The biggest obstacle to a general purpose tool usually is the compiler front end that is needed to correctly parse the code to get the entities and relations you need to visualize. Without that it’s hard to write a reliable tool for extracting the information, and if you care about multiple languages you need multiple front ends.

People do want it (contrary to the common HN refrain of “well, I don’t want it so clearly nobody wants it”). We’ve had customers where I work specifically ask for these kinds of tools. They’re just harder than they seem to write, not only for the parsing reason I mention above. For many codebases you see a giant ball of spaghetti if you look at the full graph, or the layout algorithm gives you something gigantic and hard to browse. That’s a deficiency in graph visualization tools: again, a hard problem with little good tooling out there.

I’d love to see more work in this area since there do exist people who see value in it, contrary to the skeptics.

Fully agree. A diagram is ok to describe a flow, but for complex code or systems, round tripping is a necessity, otherwise the diagram is or quickly becomes inaccurate and worse than useless. In the 90s I tried software called TogetherJ, it seemed to support round tripping really well, so well maintaining code was the same as maintaining diagrams, and led to better quality in both, along with documentation and other benefits such as relaying higher order concepts. I just did a search for togetherj and the only reference I could find was a 20 year old forum mention. Weird. I suppose there must be high end enterprise CASE software that still supports this approach, though I'm guessing most people abuse it so it's no longer respected. I think these things happen in cycles, as we can 'orchestrate' larger systems with meta descriptions of components, they become more valuable.