Live data from Hacker News

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

news.ycombinator.com

11–20 of 112 posts

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

#11

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

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.

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

#13

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

That's a great point, I doubt there can be one single modeling solution for all systems. I imagine a modern tool would be more like a suite with many options for common use cases. And it would be essential to be able to narrow down on specific subsystems maybe using something like a gitignore file

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

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

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

#15

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

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.

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

#16
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.

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

#17
post #12

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.

Embraced or been forced into it? If you want to do long term planning and design, good luck. Everyone wants to continuously change their mind on what they want/need and have the software react yet they also somehow assume this approach creates well defined systems when it does quite the opposite. Adaptation can still create reliable and well defined systems but the rate of adaptation needs to be reasonable. In agile that simply isn't the case, it's just a way to pass consumer demand and responsibility for meeting that demand right down to developers while arbitrarily placing budgetary and time constraints around that process. Development teams are often acting as small businesses anymore with similar risks but less rewards with a middle men sitting between them and the consumer, unless you work at a large tech company where that's still a little bit insulated although not entirely when product lines are killed off.

Ultimately, you just create and endless amount of complex work that keeps developers continuously busy. On the bright side there's a never ending amount of tedious work wrestling systems back into some manageable form, on the downside that work is miserable, in my opinion because much of it can be removed whth proper planning. At some point, expectations eventually meet reality no matter how many developers management burns through, at some point it's clearly not an issue with technology, it's an issue with approach and project management. By that time the organization has had enough turnover in those above and below those pushing agile that those issues too can be hand waived away and the cycle repeats.

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

#18
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.

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

#19
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.

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

#20

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…

That tool from Microsoft comes closest to what I think would be ideal, generated diagrams that aren't static and where you can include/exclude and move around components. It would definitely have to be language specific, but once things catch on IDEs implement language specific plugins soon after.
Post reply on HN