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

I find those diagrams a lot more confusing than just reading and having a mental model of the code.

Because most code diagrams would look like a solid black square.

I think the main reason is that it is slower than having a mental model.

One reason it is slower is that it is is difficult to create a map like diagram where you zoom in to get greater detail.

A decade or so ago, I was tasked with auto-generating documentation, including diagrams (super- and subclasses, to begin with), of a fairly large system in a domain-specific language developed over the past couple of decades. The language had a kind of multiple inheritance (a traitlike system), and at the time around 1500 types/classes/traits/mixins/whatevers, with the entire system all queryable at runtime (and indeed that’s how I generated it—someone else provided Python bindings to the system, then I traversed it all in Python). Just to amuse myself, I generated one class diagram of the entire system. It was around 30 metres wide and I think 30cm high when I zeroed all the margins and padding I could in GraphViz. Flipping its orientation, I got it to be 15 metres tall and almost 1 metre wide. I figured it could be fun physical wallpaper for the office, but in the end settled for just a labelless rendering with random line colours as a desktop background. It was pretty.

But more seriously, it depends on how complex the system is and how it’s modelled. The case I was working with then transferred excellently to such diagrams (shallow and deep inheritance, and other forms of composition and linkage, with every box a link) and key-value property sheets about the types and the likes, but I don’t think I’ve encountered another system where anything even vaguely like that would work particularly well.

I have used visualization generation tools but have found them of limited utility to me. When the generator is built into an IDE, the artifact it generates is less useful than the IDE itself, which typically provides a structural (symbol tree) view of the code as well as symbolic navigation ("Go to definition/references").

A visualization can be helpful as an artifact for non-technical colleagues, but I always end up hand-rolling those diagrams to highlight a specific aspect of the system and hide irrelevant features.

I’ve felt the same problem. IntelliJ markdown files have support for mermaid is and plant uml diagrams. You have to Google/tick a box to enable it though.

I find creation of a sequence diagram with class instances as columns and method names as arrows can help visualise things.

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.

Even a few very basic UML diagrams (Use Cases, Class, Sequence) can form a very effective introduction to a system.

I feel that people have just embraced Agile blindly and simply forgot about basic modelling.

CASE Tools with round-trip engineering need to make a comeback.

To answer your question, people do use various tools to extract Class Hierarchies, Call Graphs, Cross-Reference listing etc. The other HN thread that you have linked to contains some details. Lots of people do use them. You can easily add Doxygen/CFlow etc. to your make files to generate the diagrams during every build. The key thing for usage is that do not try to comprehend the entire system as a whole (all but impossible for large systems) but localize your study to a module at a time. Once you have the different pieces mapped out, you can combine them by hand.

One issue is that a general visualization tool might have have a lot of problems jumping from a codebase in language X to a codebase in language Y (let alone a mixed codebase). MS seems to have this Code Map tool but it looks like it's for C# / VB mainly, with some C++ support.

https://docs.microsoft.com/en-us/visualstudio/modeling/map-d...

In many cases it might really be faster and easier to just diagram things out with a pad of paper and a pencil compared to setting up a tool like this and getting all the parts working correctly without any bugs.

That said, a virtual reality 3D tool for visualizing code base dependencies, internal structure, what parts call what other parts, internal exception handling etc. would be pretty cool. Maybe it's an area where AI machine learning could do something.

Maybe it'd be neat.. but, I think sometimes "the map is not the territory" goes both ways. - I probably want a diagram to be simpler than the actual system.

With a manually constructed diagram, I have leverage to handwave irrelevant details away.

Perhaps to compare with documentation: it's easy to automatically describe things like types, and maybe callgraphs, but there's value in having prose which explains details about the interface which the program's type doesn't reveal. - With diagrams to visualise a system, the significance (or incidental nature) of the relationships may be hard to pick automatically.

This isn't a tool for generating diagrams from actual code, but I have really enjoyed using PlantUML lately while putting together design or architecture proposals: https://plantuml.com

As someone who is not a very visual person at all, I found it really nice to use to make my design docs more comprehensible to visual learners. I've gotten good feedback about designs every time I've used the tool.

One of the problems is: what is the language to describe these diagrams? We do have UML and it's various variants: PlantUML, Mermaid but these are too low level to prescribe conventions over how to use these to describe complex architectures. A sequence diagram could describe anything through customer journeys, rest api call patterns to call stacks within a VM. Granularity/level of abstraction needs to be captured or else you end up with metres squared of boxes that cannot be parsed at a glance unless you're Rainman.

The closest I found that solves this problem is https://c4model.com/ but you still need the code to turn your code into these markups. Can this be well inferred from code alone without framework specific interpreters? I doubt it.

And then you still need a frontend to zoom and navigate the ridiculous amount of hierarchy found within any modern software architecture, e.g microservices.

It also doesn't help microservices patterns also prescribe that you don't share repositories or code. So now you also need to pattern match untyped references across these codebases.

This is a lot of convention and tooling that I'm not sure exists.

Edit: and this is before even getting into version control and reconciling the target->as-is iterative loop.

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.”

I've already mentioned this on the other thread (https://news.ycombinator.com/item?id=31569646), but my friend and I have been working on https://www.codeatlas.dev as a sideproject - it's a tool for creating pretty (2D!) visualisations of codebases, while providing additional insights via overlays (e.g. commit density, programming language or other results from static analysis like dead code/test coverage/etc.). For example here's the Kubernetes codebase visualised using codeatlas: https://www.codeatlas.dev/repo/kubernetes/kubernetes

At the moment, codeatlas is just the static gallery, but we're only a few weekends away from releasing a Github action that deploys this diagram on github pages for your own repos - if you're interested, feel free to watch this repo: https://github.com/codeatlasHQ/codebase-visualizer-action

OP, how close is this to what you had in mind in your question?

EDIT: fixed broken links :o

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.

i think the hype is producing working solutions over documentation

the hype is producing working solutions over docs

because a code diagram is no different than reading the actual code, it'll be just as confusing. the learning occurs when you create the diagram yourself.

they are not useful at all.

I want to see the big picture, what they can generate are direct translations of the code down to the line level.

When UML was 'cool' I remember that at work some poor soul was tasked with producing UML diagrams using a $$$ tool, of course the tool failed and the poor guy had to manually produce most of the diagrams, which were obsolete quickly..

I was so happy not being the one doing this useless task..

> Why isn't diagram generation automated as part of the build process (UML or otherwise)?

I vaguely recall Visual Studio has this option where you can generate some sort of class diagram. It looked like shit the last time I used it (~2019) especially as your classes get more and more functions built into it. I also can't imagine how shitty it looks for codebases that have a significant coupling problem.

Furthermore, creating a UML diagram is a documentation process rather than something that should be automatically built in. I put it on the same level as writing a document in a word doc or something that's done as the project gets closer to being finished. Some places can live with it, a lot of places (actual software companies) probably do not as they move unreasonably fast (Agile) which does not even allow time for documentation or they just purposely neglect documentation.

> Why aren't code visualization tools more popular? The options out there seem outdated

Because they look like shit. I tried mermaid with markdown, I was not happy with the results, I tried plantUML back in 2019, I hated how it ended up looking, I hated how I have to install java for it, and I gave up on it pretty quickly.

The only code visualization tool I ever use is either draw.io or MS Visio. At lease there's a plugin for that for VS Code.

> Would you want to use these tools? What would be your ideal tool?

Markdown with vim option. It also must have an option to force a top-down flow approach and not freaking forcing it to be a left-right layout