Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

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

news.ycombinator.com

Post reply on HN
Print view View original

101–110 of 112 posts

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

#101

Post by parker01011001 »

dr_kiszonka wrote: post #99

If there was software for automated code diagramming to help me quickly wrap my head around a new codebase, I would buy it instantly (assuming it was licensed like, say, Sublime Text and not like Adobe Creative Cloud). I keep bookmarking threads like this one, but I haven't found anything useful for me. The closest one was SourceTrail, which is unfortunately not developed anymore. With so much hiring and onboarding g…

I was also on that SourceTrail path and eventually found CodeSee.io through some dev communities I'm a part of. Let me know if it works for you, I could only test it on personal projects since they only offer generating diagrams and code reviews on Github codebases and we use Bitbucket at work.

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

#102

Post by akomtu »

Too many dimensions in software to draw it properly on a flat screen. Software is more like a hairy graph where each node is connected to tens of other nodes, and automatic tools can't figure what nodes are important. Even with a 3D VR immersive interface, that's still a nearly impossible task. Edit: and layout of components is just one thing, the same components would look very different on "message flow" and "initialization sequence" diagrams, while combining both diagrams into one would create a mess.

In the future mainstream languages will probably have annotations to describe "role" of various things, specifically to enable diagram generators.

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

#103

Post by parker01011001 »

trixie_ wrote: post #90

Because no one has created a good enough one yet. Maybe you can. I am in desperate need for something like that and often just write diagrams on a piece of paper for code paths I am trying to understand or debug. Many things were just ideas for decades until someone figured out the right way to do it. This is one of them. You'll know you're close when coding with the diagram is faster/better/easier than without.

There's a few that comes to mind: SourceTrail and CodeSee.io

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

#104

Post by prbs23 »

I totally agree that having visual diagrams of a code base can be super helpful, especially when getting familiar with the code, or onboarding a new engineer. However I don't think we see automated tools because generating a useful diagram from source code is not a solved problem.

Fundamentally I think that the useful kind of software or system diagrams are always abstractions of the actual code. Figuring out the correct abstraction for the intended purpose requires either experience or a lot of trial and error. It may be possible for very specific applications, but I kind of doubt there is an algorithm to generate the content for a useful system diagram from the raw code.

Then there is the problem of rendering and layout out the diagram automatically. We have Graphviz and Mermaid, and probably others I haven't heard of, and while these do an okay job, I've never found their layout algorithms to be particularly great.

Overall, I don't think anything is going to be as useful as a manually drawn diagram, made with a specific intent in mind.

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

#105

Post by DriftRegion »

I'm surprised no one's mentioned Simulink, LabVIEW, Pure Data, and GNU Radio where your code is the graph.

Sticking to the spirit of the question, I will categorize the tools mentioned in the comments. They solve very different problems, so the "ideal tool" absolutely depends on the task at hand. I think this rough categorization can help to select the right tool for the job.

The first class of tools are drawing tools. These tools aim to aid design and communication. plantUML http://www.plantuml.com/ is best suited to manual use. I use plantUML when sketching out designs. It's great for thinking about and communicating state machines, system architecture, and server-client or multiprocess interactions. The problems solved by plantUML can also be solved by general GUI diagramming software like Visio or LibreOffice Draw. I'll not dawdle on the pros and cons.

A second class of tools are static analysis tools. These are more of a microscope than they are a sketch pad. They operate on existing code and the user input comes as filters or options to get the desired level of detail. The examples here all produce graphviz .dot files:

bazel query for dependency graphs - https://bazel.build/docs/query-how-to

Doxygen C call graphs and struct inheritance graphs - https://www.doxygen.nl/manual/diagrams.html

radare2 generates call graphs from an .elf file - https://reverseengineering.stackexchange.com/a/9120

A DBC visualizer (CAN bus protocol specification file) - https://github.com/driftregion/dbcview (mine)

These tools are great not only for probing the depths of an unfamiliar codebase but also because they give insights to people already familiar with that codebase. For example: statically generated callgraphs showed that some debugging hooks had been left in. They've also shown duplicate code paths.

A third class of tools mentioned in the comments are dynamic analysis tools: profilers, tracers, debuggers. These are the oscilloscopes and signal analyzers of software engineering. These seem to be outside OP's query.

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

The output of class 1 and 2 tools is used in builds. Doxygen supports plantUML (class 1) and callgraph generation (class 2). Class 1 is obviously manual, and class 2 is also manual for reasons that others have mentioned here: namely adjusting to get the right level of detail. The text output of class 3 tools is often used in CI as a pass-fail indicator.

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

My anecdotal experience is that these tools are specialized and therefore have a small audience. They solve problems related to design and analysis of software which is a small part of "real world" (sorry) software development.

edit:formatting

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

#107

Post by chrismatheson »

CipherThrowaway wrote: post #68

Boxes and arrows are a bad representation for complex systems with detailed relationships. Legible diagrams are limited to high level representations of a system where many details are left out. Constructing useful high level views of complex systems requires human judgement. Generation of legible diagrams could be accomplished on a domain or framework basis where code is subject to local patterns and can be structur…

I wonder if one could feedback into the other though?

I want this diagram from my code because it’s a simple way to understand the system, ok then you better refactor your code to match that simple abstraction…

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

#108

Post by parker01011001 »

mattm wrote: post #65

When I took on a tech lead role, I began to understand the importance better of having diagrams available for key parts of the system. It just becomes so much easier to explain to people and get them up to speed. I often find myself referring back to the diagrams as well to refresh my memory quickly. After trying various diagramming tools and dragging around boxes and lines, I settled on PlantUML which makes diagrams…

I hear you on having detail to be useful and not an overkill. As echoed by others, I usually bookmark threads like these to find a tool that can help, I've found SourceTrail and CodeSee. Have you used either one?

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

#109

Post by irrational »

SOLAR_FIELDS wrote: post #83
irrational wrote: post #82

At one time I had a diagram of our database schema. Every table with its columns and data types was in its own now with arrows indicating foreign key relationships. Each table was color coded and then then grouped into related areas of concern (user tables over here, retailer tables over there, etc.) We had our print shop print it out at the largest size they could (about 3x5 feet) and hung it on the wall. We referre…

Theoretically a proper tool would be able to generate this on the fly - lots of tools to do this on the database side. I’m not aware of many good tools that can do this on the application side - perhaps someone can chime in with some platform specific examples?

But the tool cannot automatically color code certain tables and visually group them together. That is where the real value lies.

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

#110

Post by zipperhead »

NonNefarious wrote: post #88
flohofwoe wrote: post #80

I think UML (etc...) was one of those things that look great on the surface but once you start diving deeper all the problems hidden under the surface become overwhelming. If a thing has been tried many times in the past and even with a lot of money thrown at it, yet it still disappeared into obscurity, then it's a pretty good sign that the idea wasn't great to begin with. In practice it's the same problem as "noodle…

Plus, if it's as much work to create a diagram as it is to do much of the programming (not to mention maintaining it), you're just not going to do it. One type of diagram I have found to be truly useful, though, is the sequence diagram. I needed to integrate someone else's library into my application, and having this was a huge help. If anyone has a pointer to a good sequence-diagram generator (that runs on Mac, pref…

PlantUML does sequence diagrams very nicely, using a pretty simple markup language. It becomes very easy to draw up sequence diagrams quite quickly after using it for a short period of time.
Post reply on HN