Hacker News Reader

Comment by cubano | Hacker News Reader

Quick question that I only ask because of my 30-odd year history as a corporate contractor...

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.

View on HN

Completely agree. Systems change, people that work on them change. A diagram gets obsolete very quickly.

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.

For groking relational databases and schemas, I find Dbeaver is good for producing an entity relation diagram in relation to a specific table (as well as an overall ERD)

I've been developing software professionally for 25 years. I've never found them to be useful. Even if you have them, they're usually out of date, and anyway they don't really help answering the questions you have. None of the places I have worked at have put a lot of emphasis on UML diagrams.

I tend to write up (not necessarily formal UML) diagrams in 2 cases:

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

I'll add (3) When I'm learning a new system, especially if it's big and/or old.

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.

(4) Security audits

Just 15 years here. I've worked at somewhere where they did put a lot of emphasis on UML diagrams.

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.

What would be useful is the ability to generate diagrams like UML from an AST. I'm sure theres already a Rust crate for it out there somewhere...

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.

A lot of tools exist for generating UML from code (and some for generating code from UML).

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.

Ditto, except that I have 30 years professional experience.

As someone who's been in software development for only a couple years by comparison, I don't see huge architectural changes happen too often for any of our products. This is something that I'm currently trying to improve upon within my company, but I've gotten pretty discouraged with all these comments lol. Is there any way to mitigate the obsoletion of these models?

Make a tool that generates architectural diagrams from the code?

This is why I dislike it when technical documentation itself becomes a goal. Detailed documentation never seems to be up to date in the real world. I've had far better experience with concise documention about high level concepts and structures and diving into the actual implementation for any details.

It's pretty straightforward - if it's pdf it's not versioned. If it's not versioned it's a fossil. The only thing I've ever done to reason about a new system is read the tests.

Ha-ha, the joke is on you, the systems I have inherited do not have tests.

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.

These days I preach the gospel of the project README: One file, Markdown format, versioned with the code, that says what the project does with high-level concepts, and how to build it and run the tests.

I second that. Reading tests is often more efficient than trying to learn about a system through documentation.

maybe - but the codethat's the hardest to understand (age, size, immature) is often the least tested, or worse the tests have been gamed over time because the previous assumptions are no longer relvevant & the code has changed so much new developers just want them to pass.

related aside - In my experience developers are much more likely to cut out old code than they are to remove or refactor irrelevant tests

I really appreciate having a high-level diagram of system architecture when joining a new project. It gives me an instant feel for whats going on and even if its slightly out of date it gives context to the evolution and design decisions of the codebase since then. That said, there's nothing that beats the good ol' step debugger and diving into the code first hand. They're complementary. Without the diagram its kind of like building a mental model of a room by feeling it out in the dark.

Edit: I'm not too strict on UML exactness, as long as it gives a feel for the components, data flow, etc.

And when you can't debug... since no person in the company can build the code in Eclipse, or run it locally.. you look at the gigantic logs full of soap xml dumps. At least that's my experience.

I would use them if they existed. I usually spend the first couple months of my tenure with a new team documenting the product after I ask a few questions and inevitably people start giving me answers that are rarely consistent.

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.

"WORKING PRODUCT, over comprehensive documentation"

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.

> Software changes too fast to make a static snapshot of it.

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.

Agreed, the architecture diagrams I usually look for are high level, mostly about how different systems are connected. These don't change that much.

When looking at architecture diagrams, usually you don't want them lower level details anyway, they would just obscure the big picture.

I worked on a project that needed to implement regulations specified in legal documents. An analyst did work on reading hundreds of pages of legislation to extract UML diagram representing the objects and their relation sand also all constrains defined by the legislation. In this case, it was quite useful to have UML as an intermediary and not force developers to be jurist. The UML documentation was checked and validated by expert of the domain.

They are useful in articulating high-level insight on how systems integrate together.

A well done diagram would have an as of date, and some commentary along side boxes.

>> A well done diagram would have an as of date

maybe we should promote a "best before" date for technical artifacts...

How would author anticipate the freshness of that diagram? Not possible I say

UML Sequence diagrams are useful, if they are kept up to date and reflect reality. I find they are great for the initial "what the hell is this doing?" stage of coming to something new.

The best way I like documentation is via a docs/ directory within the repo. Uing js-sequence-diagrams ( https://bramp.github.io/js-sequence-diagrams/ ) to create self-contained one page diagrams (like this https://jsbin.com/jusiyusowu/edit?output ) which go into code.

That allowed me to include documentation updates in the code review.

Yes.

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

I'd like to support this statement that I do not remember the last time I used them as well...

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.

I have. When they are up to date they are useful and easy. There is only one time I've seem them up to date: the UML was used to generate the headers (we used C++ at the time).

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.

In certain cases they are required. For example - compliance audits of varying flavor require architecture diagrams. To be clear, I expect that auditors understand less than 1% of what they look at in a diagram or why certain systems look the way they do, but it is a requirement none the less.

Planning is highly useful, plans are useless.

Reply on news.ycombinator.com