All three companies I have been at make heavy use of architecture diagrams, though their rules and prevalence vary from team to team. In fact I can't imagine a high functioning software organization taking a project from requirements gathering to production support without having ever made an architecture diagram. However, teams usually do not follow any hard rules like UML. A box with text, a connecting line, and a…
Ask HN: Visualizing software designs, especially of large systems (if at all)?
81–90 of 129 posts
Re: Ask HN: Visualizing software designs, especially of large systems (if at all)?
#82The 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
Re: Ask HN: Visualizing software designs, especially of large systems (if at all)?
#83So I usually find myself in the same position of using jump-to-definition and trying to get a handle on things that way.
From there, I'll sketch a simple diagram on paper to aid my own understanding of whatever piece of the system on working on. Personally, I'd avoid software diagramming tools at this stage. A simple hand drawn diagram can be extremely helpful and doesn't take long to create.
After a while, I'll often start sketching out a more comprehensive system diagram with the database(s), processes, etc. At this point, I'd ask management about working on this because it can be a time consuming process that involves talking to a lot of people.
In my experience, this has usually been an uphill battle and somewhere between difficult and impossible to take on as an individual developer, but I think it's worth a try. Taking this kind of initiative could lead to career advancement, but I've often found that there's a lot of resistance and it's not seen as a priority.
It might seem a bit cynical, but as a junior or even intermediate developer, I'd also advise caution against stepping on anyone's toes. I'm not sure why, but some people tend to get defensive about this kind of thing.
Re: Ask HN: Visualizing software designs, especially of large systems (if at all)?
#84For 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 that topic take a look at Moose[2], a dig a little bit in the research papers. (honestly I tried Moose a few times, but I wasn't very comfortable with it).
For TypeScript projects, the TS compiler API is extremely powerful and easy to use. You can use that to extract information and analyze the code relationships (Graphviz is your friend here :) ).
[0]: https://link.springer.com/book/10.1007/3-540-39538-5 [1]: https://web.archive.org/web/20150428173717/http://www.intooi... [2]: https://moosetechnology.org/
Re: Ask HN: Visualizing software designs, especially of large systems (if at all)?
#85Re: Ask HN: Visualizing software designs, especially of large systems (if at all)?
#86And a jpg with an iPhone to digitize the sketch.
Documentation is a practice not a tool.
A shitty process can be improved.
Without process "the perfect tool" just sits collecting dust.
Or a person wants to start documenting, so they shop for documentation tools.
Now they have two problems.
Good luck.
Re: Ask HN: Visualizing software designs, especially of large systems (if at all)?
#87This 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…
Good stuff. I am doing similar things but have not been murdered yet!
Re: Ask HN: Visualizing software designs, especially of large systems (if at all)?
#88I spent a number of years as a traveling consultant fixing problems... I guess it was aligned with what the cool kids call Site Reliability Engineering these days. Some company would have a crisis and I'd go in and fix it. So basically I had a matter of a few hours to learn as much as I could about some huge system that had probably been built over many years by a whole lot of people. To do this, I used a number of g…
> So basically I had a matter of a few hours to learn as much as I could about some huge system that had probably been built over many years by a whole lot of people What are some of the open source tools that you are referring to? Within a few hours, I can imagine it being difficult to integrate and deploy your tools into an existing stack. But if you are tapping into some mirrored network port, that would make more…
Re: Ask HN: Visualizing software designs, especially of large systems (if at all)?
#89We like using PlantUML and it embeds in Asciidoc nicely. Also the C4 Model seems cool but I don't currently use it https://c4model.com/