A diagram is mostly valuable in the design phase for me and to have faster less ambiguous discussion with people.
In the systems that do not drastically change, it is sometimes useful later to understand how the system was initially designed by new people.
But for specific part of the system I always have to look into the code on source control. Git blame and diffing commits have become the only good tool able to tell me what I need and also help me to realize what changed overtime, by who and when.
I remember seeing some version control tools for diagrams but unfortunately unless the design is updated as the code gets updated, these tools are worthless.
Comments that are in the code get outdated. There is little hope with diagrams.
The exceptions are tools that get their data from the system. In a company I was working long time ago, we had a GUI to connect parts of the systems. The changes in the UI became real changes in the system. That data was always updated.
For MySQL databases in the past I used a tool that was able to create the table diagram from the schema in MySQL but I had to spend quite some time to rearrange the tables with drag and drop. It worked of if people defined foreign keys and kept the naming consist.
1. I'm brainstorming with myself about how I want the software to behave
2. The software is basically done & tested, it's unlikely to change, and communicating the behavior to other people is of value, especially when describing a system that spans multiple components
The idea is that if I go to the trouble to document it then the next person won't have to; this is seldom the case because as stated above the get out of date so fast. It's still a great way to learn and confirm your understanding though.
To the point they had a product where some of the code was generated from UML, not once moving from the initial design to code, but repeatedly every time the design became out of date. It became the project everyone tried to get away from and project all new joiners were thrown into the deep end on, many quitting as a result.
A couple of years ago I interviewed for a contract role with a sister company and they waxed lyrical about their love of "best practice" UML in the interview. I declined the offer, I'm too old for worrying about which arrow type to use when no one reading it's going to understand the significance anyway. I think there are a lot of attempts to move away from code because it's complex, but the bottom line is it's the best we have for now.
Then it could just be the case where you pick out a root struct / mod / something and a depth and let the software generate you a pretty graph to stick on a slide for the meeting in 15.
I've never found any of the generated UML to be helpful (too big, too many details, and too much effort for me to simplify). Funny enough, Visual Studio cut out the builtin UML designer from VS 2017.
Joke aside, tests are a great resource when they are present. The other technique I have used was to look at the system like a black box, and only look at the expected behavior at the boundary. Sometimes, it is the fastest way to clear old cruft.
related aside - In my experience developers are much more likely to cut out old code than they are to remove or refactor irrelevant tests
Edit: I'm not too strict on UML exactness, as long as it gives a feel for the components, data flow, etc.
After those diagrams are created, usually everyone is SHOCKED that discussing the system becomes so much easier.
Unfortunately, modern software teams don't value documentation and that's the source of a lot of miscommunication, slowdowns and frustration.
Software changes too fast to make a static snapshot of it. Its the same with comments in the code, few months later what was there is no longer valid and only creates confusion.
But i can understand managers dont like that because it makes it harder to replace ppl.
Architectures don't really change that fast or often, except maybe in the initial phase. That's why most UML diagrams are a waste, they are concerned with low-level details like classes or internal interfaces.
When looking at architecture diagrams, usually you don't want them lower level details anyway, they would just obscure the big picture.
A well done diagram would have an as of date, and some commentary along side boxes.
maybe we should promote a "best before" date for technical artifacts...
That allowed me to include documentation updates in the code review.
- But is "out-of-date" the problem? "round-trip" UML tools, auto-generating UML from code, seemed like a great idea once (e.g. Rational, Together), auto-keeping UML up-to-date. They don't seem popular now.
- Is UML the problem? (IMHO: no. It's good enough to be useful; like, no matter how bad XML is, it does work).
- Or is it that the devil is in the details, and you just can't summarize code?
IMHO, docs of architecture would be the most useful of all docs. Design patterns, javadoc-like tools, type-systems and UML all try it.
In the end, understanding the domain problem is the key to understanding the solution approach, which is key to understanding its architecture. That's a lotta understanding.
In practice, I inspect source, stepping through manually - your way's better.
Most of the time, they are accompanied by company (or team) specific TLAs that I do not understand, at the time of starting, anyway.
For instance, 1 year ago I joined NXP, which is a HW oriented company. I tried to study the UMLs, which for instance, described how CMSIS packs are delivered and how they are split into DFPs, BSPs and SWPs. At that time I had no idea what the documentation is about and I've rather started incrementally building my mental image of the whole system. Looking at the UMLs now, I understand them, but I can still clearly see that they will only confuse a newcomer.
If the build process doesn't force the UML to be kept up to date, then you should only do white board uml: draw the diagrams on a whiteboard, and erase the whiteboard two weeks latter.
Does anyone here really use those UML-based docs to actually learn the systems? Or do they do what I always did and use the trusty step-debugger for a few days and come up with your own mental model of them?
Inevitably, unless someone is working full time on them, they are incomplete and several months out-of-date, and that makes them worthless really.
That's my anecdotal evidence against generating them. I'm at least somewhat sure someone has a conflicting story of how UML "saved the day", but it would be so rare to my experience that I would love to hear it.