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

61–70 of 112 posts

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

#61

Post by mattm »

tehbeard wrote: post #57
rjsw wrote: post #55

Earlier quoted context omitted.

The OP is asking for diagram generation not code generation.

Which are two sides of the same coin, transformation of code Diagram. The industry couldn't get the simple one of those (diagram -> code) to work well enough, how would they do the much more complex reverse? Architectural and even library nuances can't be easily quantified to a particular UML symbol unless you go through the effort of classifying it for every library/design pattern, and keeping that up to date as wel…

Not really the same thing. With diagram generation, the code is still the source of truth. There would just be a way to automatically visualize it.

With code generation, you would program by diagramming up front and then the code would be generated from that.

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

#64

Post by abathur »

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

I've had a related thought/desire percolating... roughly: I wonder what interesting levers we could build if it was normalized (for both toolchains and projects) to create and publish the plaintext relationship graphs in a common easily-reused format.

I'll self-reply to elaborate a bit.

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

#65

Post by mattm »

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 much much easier to create and modify. It cuts out a lot of the pain of diagramming with the mouse which means there is less resistance to creating diagrams and I do it more.

To your question, "Why isn't diagram generation automated as part of the build process" - one thing I've found that would be difficult to solve is the level of detail you need in the diagram. For instance, in a very complex system with many decision branches, a diagram with every branch would not be helpful. There are cases where I want a high-level component overview but don't want to clutter up the diagram with lots of details. And yet there may b cases where I do want some more detail but may be only in a certain section of the code. I think this judgement of detail tradeoffs is what would be the hardest problem to solve for diagram generation tools. You want enough detail to be useful but not too much to be overkill.

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

#66

Post by dahart »

lurker137 wrote: post #39
dahart wrote: post #26

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 ev…

The thing with profiling tools is that they're more focused on the details than the big picture at the system level. I'll definitely be using flame graphs more though, thanks for the tip. Also you are absolutely right about waiting for others to make the tools, but sometimes the tools don't exist for a good reason that I wouldn't have realized otherwise.

Yep, that’s totally true. Profiling & debugging tools are designed for sampling the behavior and performance, and not primarily for understanding architecture. Still, they’re great for inspecting call stacks, which can be pretty damn helpful for certain parts of understanding the code.

IMO there’s no real substitute for getting the design explained by the people who designed it. (Of course this isn’t always possible, but when it is, take advantage.) Automated tools can never prioritize the explanation nor summarize what parts are critical or tricky vs what parts are incidental or trivial, and they can’t tell you which parts should be redesigned because they were slapdash vs which parts look ugly to a newbie but have a long list of hard to see requirements, and touching things should be done with extreme care. Good diagrams are very helpful, but best used as a supplement to in-person stories, in my opinion.

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

#67

Post by abathur »

abathur wrote: post #64

> - Why isn't diagram generation automated as part of the build process (UML or otherwise)? I've had a related thought/desire percolating... roughly: I wonder what interesting levers we could build if it was normalized (for both toolchains and projects) to create and publish the plaintext relationship graphs in a common easily-reused format. I'll self-reply to elaborate a bit.

For a concrete example, I've been developing a tool (https://github.com/abathur/resholve) that can ~build/link Bash/Shell scripts--i.e., rewrite them with external executables converted to absolute paths. (This helps ensure dependencies are known, declared, present, and don't have to be on the global PATH for the script to execute cleanly.)

There's a devilish sub-problem, which is that any given executable can potentially exec arbitrary arguments. For now I handle this with a very crude automated binary/executable analysis that needs to be augmented by human source analysis. Deep multi-language source analysis wouldn't be very scalable, but I suspect fairly-standardized structural annotations could improve the results in a scalable way.

I have to imagine there are other applications of the same information.

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

#68

Post by CipherThrowaway »

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 structured "for" generation. We see this with things like OpenAPI schema generation.

Ultimately I think diagramming isn't prioritized because diagrams themselves aren't that valuable. They're just a medium for the actually valuable thing: high level representations.

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

#69

Post by rramadass »

davidy123 wrote: post #30
rramadass wrote: post #14

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…

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…

I remember both Rational Rose and TogetherJ CASE tools. Round-trip engineering was supposed to be practiced by both Domain Experts and Programmers each modifying their models and still having them all consistent with each other. But what happened in practice was that only Programmers used them who did not see the utility of updating a UML class hierarchy instead of directly updating the Class itself. That and the exorbitant pricing is why they fell out of favour. It is really a shame because with the explosion of distributed apps using a variety of languages/tools a single uniform interface modeling all aspects of the software is sorely needed.

PS: Came across the book Software Visualization - Visualizing the Structure, Behaviour and Evolution of Software by Stephan Diehl which seems to provide a good survey of the field.

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

#70

Post by mtkd »

Any high level diagram usually needs one of the architects to produce it manually in the context of the audience and what aspect they specifically need to know about the structure/logic

In most complex systems the part where the magic happens is likely impossible for a tool to identify so would get lost in the noise of the cruft around it -- even for monoliths using frameworks and especially for anything distributed across microservices, and it's usually that aspect that is of most interest

Post reply on HN