91–100 of 129 posts
I like using https://c4model.com/ - the Level 2 diagram is particularly useful. I use https://mermaid-js.github.io/mermaid/#/ for the diagram itself because Github natively supports it in markdown files, so you can revision control the diagram. I managed to get reasonably close to the C4 diagrams minus a few features that mermaid does not support.
Welcome to the industry! sobs in time constraints
> So, is it a good idea to try documenting the code design through some sort of visualization?
Yes, I think it's a good idea, though I'm afraid I don't have much advice on how to accomplish that.
The problem I've always had is that there's so many ways to cut up a system. Some people want higher-level architecture diagrams, that show how all the various systems fit together. Some people want infra diagrams showing what VMs, DBs, cloud resources, etc., are all wired to what else. Some people want sequence diagrams detailing RPC/API calls between systems/component.
Invariably, for whatever documentation does exist, the person wanting documentation wants the diagram that doesn't exist.
I've tried PlantUML, but it is complete garbage when it comes to emitting useful diagnostics. Paired with a language that seems to be nothing but special case after special case, and the result is basically unusable.
This tool is good for making simple UML diagrams and even lets you do it with simplified syntax https://plantuml.com/ I'd say the big problem in visualizing big systems is that you can't usefully do it in one graph. For instance I worked on a system that had 2000+ database tables if you were going to make a diagram of that which shows everything it is going to take up a long wall. (This can be useful, but it is a big…
That’s because it’s flat
Imo this changes the game
Imagine being able to make a fully 3D graph inside a space the size of a large building
What you are looking for is called "Program Understanding". If you Google for it you'll find a bunch of research papers on the topic. For some reason, tools related to program understanding are not widely adopted by IDEs. A while ago I used a tool for Java that was based on the Object-Oriented Metrics[0] book by Michele Lanza. But, that tool was discontinued and it doesn't exist anymore[1]. If you are interested in t…
For a small but complicated project I got thrown into a while ago, the only way for me to understand it was to print out all the source directly, vertically tape together the pages for a single file, and then lay them all out on a huge table. Then I took multicolored markers and started physically drawing out the call chains. I then I sers-toi the system, and also found an enraging bug: the system widely used the var…
The time of UML came and went very quickly. No one misses it. These types of diagrams are either not specific enough to answer any useful questions or so dense and insane that no one can read them. If you have a business requirement with a decision tree it is probably a good fit for this type of documentation - write it down in DOT or asciiflow or something
It's interesting because it attempts to capture domain knowledge isolated from a programming-centric view /metaphor which makes it challenge to discuss complex systems with staff other than programmers.
I gave this a bit of thought earlier this year ( https://alexanderell.is/posts/visualizing-code/ ) and, with the help of HN commenters, collected a small list of ways people are working to help with code visualization. I don't think most of them are production ready (some are just research papers), but you may find them interesting all the same. SoftVis3D ( https://softvis3d.com/ ): where a "‘code city’ view provides…
Sometimes I wish I could project my IDE onto the wall behind my monitors. Programming in VR would probably achieve the same thing, but I'm not ready to move into that world yet.