I'm still waiting intently for debugging tools to be able to create * object * diagrams of an running app. Debuggers are excellent, but I keep forgetting, if the object in question is @Hdj637 or @HU83NS
I just referenced the concept of multiplicity in the values of pytest fixtures a single fixture may return just yesterday and I referenced it in the context of UML to make my point. Numerical distinctions in instance counts and collections and what not is a valuable articulation I think UML encapsulates. Maybe there’s other ways to communicate this concept but if someone talks of multiplicity in software design UML is directly where my mind goes.
Used consistently it really helps a lingua franca across teams. Which was the UML aim all along, but it got caught in into "Enterprise Bloat" (like SOAP or XML)
This title and article feels plucked out of my brain. Most of my work is a lot of integrations and the best way to get a room full of devs to get what is going on is via sequence diagrams. Every other method, formal or made up, is weak compared to a basic sequence diagram. You can expand from there if needs be but I find it gets people thinking in a more complete way, gets the details out and what ifs and what abouts, and then you have a nice target that teams hit with very high accuracy and completeness.
It is one of the few (only) diagram types that is easy to draw and fairly close to the real world implementation. Most other formal approaches are wonky abstractions that only true practitioners can make sense of.
Spot on, I agree that sequence diagrams are super useful, I see them used all the time in FAANG.
I do really wonder why UML is still taught in universities, as the article states, it's pretty useless. I took a masters Software Engineering course at Georgia Tech two years ago and a big part of the class was learning UML. That time was mostly wasted as I've never used any of it and never met anyone who has used it.
It wasn't my first time learning it either, we also had a section on it in my undergrad software engineering course. So I learned the same useless stuff twice.
Why the university teaches outdated useless stuff? My guesses:
- For the university, it fills out offerings and takes up credit hours, keeps the tuition dollars flowing
- For the teacher, it's something they already know how to teach, so it doesn't require nearly as much effort to teach as something more useful but maybe less familiar
- Universities are trusted with the decisions of what to teach and don't face much short-term accountability, so there's no real downside to teaching a useless course for another year
- They probably don't know it's useless. (They also don't care to find out because of the aforementioned points)
My graduate program did not teach UML, but I did learn it during my undergrad program. It was a relatively small part of the major software engineering course. It introduced the idea of formally specifying software, and it forced me to reestablish, visualize, and otherwise integrate what I was simultaneously learning about things like interfaces and inheritance. It was presented as an educational tool and not at all that we would be using it in industry. Far from useless or out of date in an educational context.
That was my take on it. How do you get students to practice the process of thinking conceptually first, then evaluate how thorough the planning is, without some tool like UML? Its one thing to lecture your students on the necessity of planning ahead. Its quite another to evaluate whether or not they know how to plan ahead.
Granted, UML is not used hardly anywhere, but I must've learned 30 different specific software tools in college that I never used outside of college. However, I've used something like each one of them. I took a technical drawing class in high school and I still use some of the techniques I learned in that, even though absolutely no one uses t-squares, triangles, and actual paper in modern technical drawing today.
There's a fair argument re: how much planning and conceptualizing should be done ahead of starting the Agile process, and also a fair argument re: what that planning should look like (crude flowchart? UML-compliant class diagram?). But in rejecting the UML tool, are we rejecting also the idea of advanced planning too? Like, how completely do you need to reject advance planning that it takes the Agile loop to reveal that the customer actually needs software that uses an observer pattern?
There's a bureaucratic reason too. Changing curricula is not fast and can take years (depending on the institution of course).
My department profs actually got in a bit of trouble with the university because they took the course that they should use for undergrad/graduate mentoring (something like a "special studies in XXX" placeholder, usually for independent or small group study that was special enough for course credit) and used it to create their own courses outside the review of approving a new course with a distinct number and credit count.
The reason they did it in the first place was because if they wanted to change the curricula for the existing courses, remove course numbers, or create new ones, the bureaucracy would take 4-8 semesters to get approval and complete. By which time some of the material was obsolete. One of the profs got fired and the rest quit, eventually.
"Useless" is a strong word. Definitely a bit less useful than intended though.
Before UML, it's hard to capture the state of corporate software development that allowed the insanity to take part. I mean, UML was the marriage of two different approaches to drawing object models that were locked in a battle: OMT and Booch method. There weren't tons of open forums for discussion and debate like the internet has now, there were conferences and such and these guys were basically trying to create formal methods for objects in a vacuum.
It was kind of existential stuff for a lot of the smaller players in the industry, everyone saw value in this newer approach to building software. "Reusable components" seemed huge. Tooling was expensive, training was expensive. Microsoft was moving as a scary rate, connect your cart to the wrong horse and it could cost you the company... On some of the usenet forums, about the most open discussion there was at the time, I read debates about the virtue of C++ style multiple inheritance vs single inheritance and there were product matrices for programming tools that had check boxes for crap like that. C++ and CLOS both supported multiple inheritance so to the casual observer they were "better." Now I've never seen serious industrial software written in CLOS or anyone even considering it but it "had the features." It was just a different and crazy time, kind of amazing how open source/free/libre has altered things, the entire culture of building software is different and probably more healthy.
I’m on the advisory board of my school’s comp sci department. Each of us advisors has our own experience and perspectives on what useful things the students should learn. Sometimes I’m arguing that no, they probably don’t need to learn RPG, just because that’s what one of my colleagues sees a lot in their branch of industry. In turn, they argue that some of my recommendations are more useful at SF tech startups than in long-term positions in the companies local to the school.
Without those various perspectives, you end up with students learning all kinds of goofy things just because no one said, nah, they’re probably not going to need that.
Sequence diagrams aside (they are useful!), I also felt far too much time was wasted on UML in my university course. The only small argument I can see in favor is perhaps to encourage some thinking and discussion around software design among students in an educational context, even if I've never once seen it used in industry. I can't say I'd miss it's removal all that much either though.
It is shorthand for saying that it is used by engineers working on high-profile, high-impact, software that ships to hundreds of millions of people. Some people might argue that these teams work on some of the most important software in the world. So if the people who work on this important software do a thing, like use sequence diagrams, that is a decently good signal that the thing is useful.
Also used a lot in automotive software development processes for example. Basically, the more safety critical a system is the more formal diagramming / modelling there will be part of the design and development process. It’s important to be able to reason about complexities of such systems across a team / teams.
Every software engineering team in my 20+ years career actually used 2-5 types of UML diagrams: classes, sequences, deployment, activity, state. I think it mostly depends on maturity of the team and engineering culture, whether UML is used or not. There’s certainly some value in it.
With the odd caveat that you probably use sketches of these diagrams? As soon as you are trying to cram in all of the extra details stuff like class diagrams can do, you are probably wasting time.
I do not understand your question. If I do not deviate from convention but omit unimportant details, is it a sketch for you?
If you have a project document template from PMBoK, do you feel obliged to fill all the sections or you document only information relevant to your project? With UML it’s the same: it offers a lot, but you do not have to use everything to produce a conforming diagram.
It it a sketch if you don't include every detail that UML was specifically designed to convey? Yeah? Noting that a sketch is not a derogatory phrase here.
Note that, for many of these diagrams, they existed before UML. It was an attempt to formalize them. In classes, they are often used as code generation tools in an attempt to keep a 1:1 between document and code. Laudable, but I have yet to see that work out well.
To your point, I think, the same ultimately goes for document templates. Way too many are used prescriptively as a way to make a successful project. Much to the chagrin of the document writer when the project fails. Often miserably. To the point that I'm convinced most accurate project documents are after the fact. Certainly not waterfall to the project that they are describing.
> I think it mostly depends on maturity of the team and engineering culture, whether UML is used or not.
I suspect that's true: teams with a very immature engineering culture probably do use a lot more UML. It's a good way to feel like you're doing something useful instead of actually doing the hard part. Mature teams write code.
Sounds very Dunning-Krugerish “smart people like me do X and not smart people do Y”
Coding and documenting aren’t exclusive. Modeling is part of documenting. UML is a type of modeling.
I would think effective teams will want to build good software. And to build good software they’ll want to capture requirements, communicate with other teams, and test their software. Design helps with this and is part of coding.
At the end of a successful day, I should have some updated models, some code, and some running software. If someone wants to see what I did, they’d likely read through different parts.
Just like trying to figure out a stage by just reading models sucks, so does trying to figure it out by just running the software.
UML is not documentation, it's code for people who can't read code. UML diagrams offer no additional information to someone who already can read code (and write readable code). They are training wheels. Mature bike riders don't use training wheels. Mature teams don't write UML -- they write code instead.
Other forms of documentation have their own tradeoffs, but I was not discussing those. You're the one who automatically equated UML with all possible documentation.
> to build good software they’ll want to capture requirements, communicate with other teams, and test their software
UML is awful at all of this.
> At the end of a successful day, I should have ...
> “smart people like me do X and not smart people do Y”
Part of engineering culture in general, not just software engineering, is ability to share knowledge though documentation and best practices. If you share the source code, you communicate your solution on a very low level. It is often necessary to zoom out to see the big picture and there visualization helps. You can create ad-hoc diagrams, but their expressive power is low: without a convention it’s basically just space, text, arrows and generic shapes. To increase the expressive power you need a visual language in which different shapes and lines have some semantics. And here comes UML and other diagram languages. If you are not using them, it is likely that you are not communicating efficiently. Can a mature team fail at communication? I leave the answer to you.
How was it supposed to keep up? The most popular programming languages did not introduce concepts that are too hard to reflect with UML.
Or do you mean the problem of maintaining documentation?
Maintaining documentation. UML cannot go even one developer-week without being updated, but the developer will often not do that. By the time your UML is a month out of date it is useless at best, and misleading at worst.
This has nothing to do with UML. Ad-hoc diagrams or plain text descriptions become outdated at the same speed, which depends only on the level of detail that you put in documentation and not on the format if it. If you cannot keep up with the changes in the code, you are choosing the wrong level of detail, that’s it.
Ad hoc diagrams are much more likely to be tossed in the trash can after a week. If you keep them longer than the same problems apply. If you only keep them for a week than ad hoc is good enough as everyone still remembers what the symbols mean from when you created it, and the next time it won't matter that the symbols mean something different
I agree with everything you said until you got to UML diagrams. The problem with UML diagrams is that they communicate exactly the same thing that the code should be communicating. Class diagrams are not higher-level than the code they describe. Instead, communicate high-level intent and interactions.
I don't think I have ever seen anybody actually getting value from a class diagram. I have seen many people creating them, but they are always useless.
I also don't think the UML variant of state machines and workflow are any popular. But well, there is probably somewhere where people use them. Also, those lists usually ignore entity-relationship diagrams, where UML just adopted the popular format (without even minor changes, like for workflows), and thus everybody uses the UML one.
But yes, people don't remember about deployment diagrams. Those are used a lot.
> I have seen many people creating them, but they are always useless.
Not every artifact is worth keeping, instead the value can come from the process of creation as a way to structure your thoughts or to explain or brainstorm possible solution.
The value of class diagrams for those people is in the moment and it’s ok to throw them away later if they become useless.
It would be useful if everyone would at least be vaguely familiar with basic UML notation, i.e. action vs. object, multiplicity, connectors (association vs. composition vs. dependency vs. specialization, interface/implementation), class vs. instance, fork/join, swimlanes, etc. Otherwise you have to clarify over and over what means what in a diagram.
One powerful aspect of UML is that you can combine different diagram types. For example, you can use activity-diagram elements in parts of a sequence diagram.
For pragmatic use, “UML Distilled” [0] by Martin Fowler is a good introduction and reference.
>That time was mostly wasted as I've never used any of it and never met anyone who has used it.
So here's the conflict: if we agree that planning is good, communication is good, and that it is faster / cheaper to design before we build rather than rushing in to build something, then is it not a good idea to have something like UML in our tool kit? Perhaps UML was too complicated or overbearing, but I've always felt like a universal tool to describe aspects of the software we are building is fundamentally a good concept. Further, it feels like the right idea to document / designing up front in a way that increases buy-in and communicates what we are doing.
It's certainly given too much importance in the curriculum, but the idea of having a common language (with standard semantics) for sharing design decisions is valuable.
I'd argue the issue is that because UML is not seen as valuable, everyone improvises their own dialect when drawing stuff, and so since nobody trusts people following correct diagram semantics (e.g., meaning of different arrow shapes), nobody trusts the resulting diagrams either, further reinforcing the notion that it's useless.
Pretty sad assessment if it truly was useless as you say. I've found structured approaches to solution planning and design (UML, and others) to be very useful in most projects.
Although I never use any aspect of UML in my work, I absolutely benefitted from learning it. Learning how to model things in UML required me to change the way I broke down and formalized problems and solutions. That change stuck with me, and I've very much benefitted from it, for the rest of my career.
Can you give an example? Some try to put too much detail into ER diagrams in my opinion. A Data Dictionary is usually a better place for such details. ERD's should mostly be to illustrate relationships.
One trend/fad was to put words describing links between tables, but I usually didn't find such helpful. Maybe if the wording was done well it would help, but most seem forced in practice. Good naming takes experience. Maybe let newbies draft the phrases, but have someone with experience review it. I.e, mentoring.
> A Data Dictionary is usually a better place for such details.
Self-documenting code/schemas are an even better place.
...sometimes I feel like I'm the only one in the world who uses DB-level metadata (e.g. `sp_addextendedproperty` in SQL Server) to attach explanatory notes and other metadata to database objects, including columns and constraints - and it gets better because I modified my Entity Framework scaffolding templates to then include those comments in the generated C# code as XML-doc (or JS Doc comments in TypeScript) - and the entire DB schema is also kept in source-control (using SSDT).
Additionally, because CHECK constraints in SQL are declarative it means I don't need to write-up a human-readable explanation of (for example) the format restrictions based on a column in the CHECK constraint, because it's immediately visible and obvious (and yes, my scaffolding templates also include the CHECK's expression in C# code-comments too for-reference).
----
Another technique I'm a huge fan of now is using predicate-types (similar to dependent-types) by taking advantage of class-invariants: so I have my own zero-overhead (i.e. elided structs) like `NonEmptyImmutableList<T>` which immediately lets everyone know that if that's passed as a parameter then it won't ever be empty - whereas if the code used the stock `List<T>` or `IReadOnlyList<T>` types you'd have to write-up how that list should be used - which no-one should have to do.
I just lament that my daily-driver languages (namely C#) make it kinda tedious to define types like that.
I've used it for years - usually auto-populated from the model that builds the relational schema (like you had done). Same for constraints. By coincidence, I just convinced my team to start using sp_addextendedproperty.
That's the advantage of using a higher-level notation, such as UML or code-first EF, for your ORM.
I really love Mermaid Diagrams. This is one of the best libraries to come out. I'm writing a book, and being able to generate diagrams with mermaid and then customize the CSS to meet the guidelines from my editor has been fantastic. I've started including a lot more diagrams in my projects and documentation as well. It's just such a good tool.
Yeah, Mermaid gets it. Mermaid . . wait a second . . oh, ok, these are the same people that do Mermaid.js, they're just trying to make a living doing it.
Another useful chart type provided by Mermaid.js is the git diagram, which I use all the time when brainstorming change processes, especially for other folks who might not be git-conversant.
I find Mermaid's syntax difficult to use and understand past the simplest examples. I've also run into some strange edge cases with it, but can't remember the details right now.
Is there a way to get a git diagram out of D2? It does have nicely streamlined syntax.
One thing that worries me is that the profusion of text-based graph description languages will result in a family of software that's unparseable due to its success. We have Graphviz, GNUplot, PlantUML, BlockDiag, Mermaid, Kroki, Vega, and too many others to count - but we don't have a Pandoc.
> The most common failure mode for sequence diagrams is over-complication. (This also is the failure mode for most diagrams, as I wrote in an article on flow charts).
Agreed.
UML – with the goal of being a graphical language for _complete_ specification of a system (both for code generation as well as to have diagrams generated from code introspection) – has to be exhaustive, therefore fails at showing the big picture.
Use of UML that could accommodate multiple levels of abstraction would fix that. I believe this is what C4 [1] tries to achieve with 4 levels of diagram. Unfortunately everybody who invents a new diagram model also reinvents the wheel and throws the entire UML away. One could easily use UML visual language, but just standardise on using the 4 levels diagrams of C4.
I yearn for something that lets me draw sequence diagrams as human-readable ascii art (instead of declarative statements as with PlantUML,) but that is also rigorous enough to be rendered to a professional looking PNG when the situation requires it.
I've been toying with flow-based programming again, and it works relatively well as an implementation choice for the same "high level" that sequence diagrams cover: The parts of a lifeline that need to wait are reified as stalled information packets, while request/response APIs are wrapped into nodes(which I've found is a good starting point for practical application - make a library of nodes from API calls). The rest is defined by graph wiring and data types.
As a graph model, FBP lets you fan out widely, but that is something you don't actually want to do most of the time: the benefit I am seeking it out for is in the bounded buffers adding backpressure regulation and debuggability. As such I've currently settled on mostly defining ports in terms of structured data types, then doing destructuring/merging/splitting in custom processors.
i agree that rose was crap. but some other tools, such as enterprise architect were not so bad, despite the name. and the ent arch guys were always very helpful. this would be something like 20 years ago - gosh.
I work with non-distributed (ish) systems, and I use watered down class diagrams much more often than sequence diagrams.
But even when I was working on more distributed systems, I found more value in state machines and simplified class diagrams, actually. I think most cases where you're using a sequence diagram, a state machine is a better tool. Both for thought, and for implementation. Surfacing implicit state machines can require some extra upfront design, but if you have a non-trivial amount of states, it's pretty much guaranteed to be worth it.
The cross product of multiple state machines, I expect. If you try and use a single state diagram to encode the product of states, everything multiplies.
Ah, ok. That's kind of what I meant by upfront design, though. Yeah, mapping this out is gonna suck, but it's better than having it hidden in a bunch of ifs.
UML was yet another fad overdone. Many IT fads do produce useful niches or specific products, but the impression given at the time is they'll replace most of what came before. That's rarely the case. I can list about 25 "trends" like that since the late 80's. Chasing fads has gummed up too many stacks and standards.
I also find sequence diagrams to be the most useful, but disagree that the rest of UML is useless. Class, component, package, activity and state machine diagrams are all useful ways to model the structure and behavior of a system visually.
The only reason the other diagram types fell out of favor is because of the development methodology change starting in the early 2000s. The industry started rejecting Waterfall, early design and system architects, in favor of Agile, just-in-time design and empowering developers. So we saw no need for these visual design tools to model the entire system, since we ended up changing the design during the lifetime of the project anyway. The drawback of this, of course, is that with the Agile approach these diagrams never end up being made, so developers are left to assemble their own mental model of the system, which hurts the overall comprehension. Most developers IME actively reject these diagrams because they are quickly outdated, or require constant changes to keep up to date, which is true, but this is not unlike documentation, comments, and a myriad other things that needs to be synced with the code.
Yet sequence diagrams are useful in a wide variety of use cases, and let's face it, they're the easiest ones to comprehend, and are even understandable by a non-technical audience. In contrast to the other UML diagram types that have strange notations and the information is more densely packed.
I've taken a throwaway approach to diagramming, where I'll produce them more or less on demand for a meeting or presentation, but not think of them as an enduring artifact. PlantUML is my friend here because I can knock out ugly but gets-the-point-across diagrams in 30 minutes before a meeting and check them into source control, so I can then take the bones of older diagrams and rework them for a fresh meeting.
I used to whiteboard for this, but that hasn't carried over well in the remote world. What I miss about whiteboarding though is that you can tell a story as you draw, so whoever's viewing can watch something unfold from a blank slate while I'm walking them through the history of whatever system we're describing. That said, I can make a PlantUML diagram much more correct than a whiteboard.
All that said I too would love for more of that to be automated increasingly through AI. And I suppose it should make sense conceptually, because for me the value of a crafted diagram over an automated one is that no one really wants to look at the insane ERD of an OLTP database or a production object model. They want the digestible high level vision of the important bits, or the bits that are relevant to the conversation taking place. So it's a summarization problem. How to get the right data to produce a correct summary is interesting--I'm sure if I look there's a dozen papers to read on a similar subject :).
That's a great approach that has worked for me too. I think plant is a great little system. Not only can you get your point over in a handful of lines of text but I have found out that it is quite easy to generate the plantuml programmatically. So instead of having to keep docs and code in sync you can end up generating your graphs in ci. The upside compared to big diagramming products is that plant requites no boilerplate and you can provably grep and sed most diagrams out of your codebase which is a quite low barrier to entry.
> Maybe in the not-too-distant future we will have AI grokking large code bases and cranking out accurate, useful, UML diagrams out of it.
> All those diagrams, when they are complete, correct and up-to-date, do convey what they are supposed to convey.
I spent a bit of time prototyping this recently. It's definitely possible. Rational Rose also had the capability to generate diagrams from code though. I don't remember how good it was at the task though. Was Rational Rose just a very bad implementation?
I find the hate in this chat strange because diagrams are incredibly useful when working through complex problems* and then conveying that information to other engineers. My experience over 20+ years is that a huge portion of engineers can't grok complex problems from code alone.
*Most of my projects are optimizing billion+ row databases, micro-service architectures, and various other scaling challenges.
The problem isn't generating UML from code, the problem is generating useful UML from code.
Where those boxes are in relation to each other matters. You can't just randomly throw boxes and lines on the page, you need to arrange them so that boxes that we can tell what things are related by how close they are to each other. Automatic UML doesn't capture that.
Sometime you have complexity in code that needs tobe hidden by default. I don't care about rare error cases most of the time, but automatic UML can't know what is the complexity needed for rare cases and what is complexity you need to show the junior on the first day.. related to this when i'm interested in one error path how do you hide the others?
Then the real killer of both. Next week there is a minor requirement change (new features we always knew were coming and planned for even), and now the code changed. UML doesn't follow that. Either you generate UML and have the above problems. Or you manually update UML in theory, but in practice just let it slide as the week after you know something else will change and you don't nees it today anyway.
> Or you manually update UML in theory, but in practice just let it slide as the week after you know something else will change and you don't nees it today anyway.
I've heard this argument many times, but how is it different from keeping documentation, comments, tests, or the issue tracker up to date?
They all require some discipline, but if the team finds value in any of these things, they would make an effort to keep them synchronized with the code.
Besides, I suggest not falling in the trap of having formal design documents early on in the project's lifetime. Rather start with informal diagrams and sketches, and once the design has mostly settled, switch to something like UML. This would mean it wouldn't require changes every other week.
As for automatically generating, and dynamically arranging diagrams, this is more up to the generating tool than UML. These tools are still stuck using decades old technology at this point AFAIA, but there's no reason that a smarter tool couldn't do the things you mention.
> The problem isn't generating UML from code, the problem is generating useful UML from code.
I would kill for a tool that could output class and sequence diagrams from a project or component. If the format is editable and tools can automatically layout/filter out components, all the better. Right now the main time sink in putting together diagrams is trying to express what's in the code. Once that's in place, we can prune stuff we don't need.
True, though nowadays I use PlantUML (https://plantuml.com/) which is a DSL using which we can create all kinds of UML diagrams. If any changes are to be made I just need to make the incremental changes using the DSL and regenerate the images. It has been very helpful.
People who say "UML is useless" basically say "diagrams are useless". Which obviously isn't true. The alternative to UML is everyone inventing their own "diagram language" when they want to visualize something.
Moreover, I think comparing different UML diagrams can also be enlightening for university students. E.g. state machine digrams look quite similar to activity diagrams, but the former emphasize states and the latter actions. And class diagrams let you learn the connection between class structures of OOP languages and database structures.
UML lets you visually learn the abstract higher level concepts without having to rely on irrelevant specifics of practical implementations, or just on dry theoretical text.
The nice thing about visual stuff is that it is self-explanatory. Instead of needing to read a book about UML first, maybe just use some prose in addition to your diagrams, and you don't need UML at all then. That's also more flexibel.
That concept map example is only a loose association of ideas, where the nodes aren't of the same type (e.g. event, state, class etc), or sorted into types, and apparently included quite arbitrarily. Mind maps are similarly loose. UML is for when you want more precise diagrams about a fixed subject matter.
I agree on the "shorthands", like empty/filled arrows, that people may not know. But there isn't much alternative to such shorthands other than leaving them out completely, which wouldn't be an advantage. In diagrams some information is either conveyed succinctly or not at all. The "alternative" is a block of text instead of a diagram.
Not exactly related, but this concept map looks amazingly similar to a semantic ontology. RDF/OWL may not be the easiest encoding, but is quite capable in organizing very large concept schemes.
Nothing wrong, but code is already formal enough that you don't need a formal visual language (UML is not just a bunch of diagrams, it's a formal language). So yeah, a bit of drawing might help to understand, a few ideas from UML might help, but it's not like it is super necessary.
As said, the sequence diagram is a real plus because sequence information is not very well expressed by code, so that diagram has much added value.
I personnaly find UML hard to use becaues if you want to communicate your ideas precisely, you have to know much of its formalism and most often, people who read your drawings don't master its intricacies, so communication quality is no good...
> code is already formal enough that you don't need a formal visual language
Code can be formal enough but in reality it is almost never formal enough. Many constraints can be expressed imperatively (eg. someone validates the number of related objects in the create view) and in unexpected places (across repositories and libraries and maybe not even in code but in some stored procedure). And then it is all in flux and can go away the moment you change your stack.
I don't know if UML is perfectly flexible (maybe?) but its sure benefit is a source of truth that does not depend on your implementation.
The fact that it doesn’t provide any benefit or make things particularly simpler than describing them in code and projecting them to UML if you need a visual diagram. Also, the fact that it is particularly counterproductive if I’m not coding in a pure class-based OOP language, since it presupposes that the solution is centered on class-based OOP.
There a diagrams that are useful before coding, but most of them aren’t part of UML, which is a product of the simultaneous highwater of class-based-OOP-is-everything and pre-Agile industrial software development methodologies, and (except for some isolated bits) poorly fit to anything else.
> Starting with UML to describe a set of classes or - worse yet - an entire system is lunacy and a massive red flag.
I don't think this is right or a well founded opinion. The whole point of any diagram language, including UML, is to provide the means to describe software projects in different views, including class diagrams but also component and system diagrams.
What do you think is the whole point of a modeling language?
I think you are making the mistake of assuming that because something is an important motivation for a class of things, it must also be a good use for every instance of that class.
Sometimes motivations are misguided, and sometimes instances aren’t well fit for major motivations of their broader class.
> (...) it must also be a good use for every instance of that class.
You, and OP, failed to present a single argument supporting the thesis that modeling languages in general, and UML in particular, are "lunacy and a massive red flag."
> Sometimes motivations are misguided (...)
Not only did you failed to support anything in the original anti-diagram rant, now you also tried to support generalizations with hypothetical corner cases involving misuses, which is an absurd argument to make.
So not only do you have zero substance for show with regards to the original anti-UML rant, you also resort to using vague, unsubstantiated strawmen.
This is to be expected. Like many discussions involving technical aspects, generally detractors come from positions of opinionated ignorance.
> You, and OP, failed to present a single argument supporting the thesis that modeling languages in general, and UML in particular, are “lunacy and a massive red flag.”
I failed to support that thesis because I never endorsed it. Pointing out a flaw in a counterargument is not endorsing the argument it is deployed against.
> What do you think is the whole point of a modeling language?
Not building an entire system down to class level which is what it is all too often used for (in my experience exclusively by people who have never and cannot code).
It's inefficient, doesn't play well with Software Engineering (diff, version control etc..) and is a relic of the past.
Keep the classes in code, project that into a diagram for the few occasions that is actually needed, and stick to a simplified tool like C4 (https://c4model.com) for your architectural views. Sprinkle some sequence diagrams in too to help describe the key data flows (they're handy next to C4).
Why use C4 over UML? Because the vast majority of the audience don't even know what UML is. So keep it extremely simple and include a key / guide to any of the (few) shapes or colors you use so that it's completely self contained.
The vast majority of UML belongs to be put into the Indiana Jones storage facility along with other archaic ideas such as Function Points / Function Point Analysis.
> Not building an entire system down to class level (...)
That was never the point of modeling languages.
Your baseless assumption is even more absurd when you factor in the fact that modeling languages even express runtime behavior, componente, and packaging.
The main problem with these mindless attacks on modeling languages in general and UML in particular is that the bulk of their retractors clearly knows nothing nor has any direct contact with them, or how they are used in the real world. Their arguments are nothing more than poorly thought through strawmen. Your comment fits well.
> Why use C4 over UML?
See, this is a telltale sign you know nothing about what you're commenting on. Not only is C4 a modelling language like UML but it also covers the exact same responsibilities and features of UML. C4's main selling point is advocating for the representation multiple points of view, and UML is a standard specification to express all the points of view you see fit in a coherent and rational way. There is no C4 vs UML. They have both the exact same design goals and usecases.
The superior alternative is drawing a diagram on a piece of paper to exercise the mind and show to collaborators, and never setting foot anywhere close to the UML tarpit.
There are other types of diagrams beyond what UML formalizes. For example, Data Flow diagrams can be very helpful, but they don't exist in UML (Component, Composite Structure, and Activity diagrams all have similarities with Data Flow diagrams, but none are really a great fit).
Class diagrams feel pointless to me, this information works better as code, and how do you draw a class diagram with more than 10 classes and keep it readable?
I think class diagrams are a good way to visually display classes and hierarchy. If I have a package or module that has 10 classes and I want to show inheritance, properties, and methods I think it’s easier to show the class diagram then hand someone 10+ source files.
Also, class diagrams are more useful when you can’t give out source.
That being said, I think you can autogenerate class diagrams from code so it’s not like you should spend a lot of time making them.
If you use class diagrams to show the "truth" you are in painland in my experience.
However I sometimes find them useful to extract key parts of the system and showing their interaction. Cutting away many attributes, many helper classes, many other things.
That can lead to pictures which are quick to grasp and then allow further digging based on code.
Maybe before you actually start writing code its nice to create some domain diagrams which you can convert to class diagrams. Saves a ton of time. And you have good discussions about the general high level workings of an architecture. Can be done on a whiteboard. Make some pics and start coding.
Assuming that you're using a modern IDE: it is an order of magnitude quicker to model the domain (classes + attributes) in code and project them as diagrams, say with graphvis.
High level boxes are great for thinking about systems but the key there is abstraction - minimal viable level of detail..
Dont you want to discuss and talk about a design before you even touch a keyboard? In my projects we always discus high level overviews with pen and whiteboards. Nobody should even dare to touch a keyboard.
Absolutely, I pretty much always start with design sessions on a whiteboard (or if remote a call using draw.io).
That discussion is almost never going down the the level of an individual class and NEVER adheres to the UML standard.
Very occasionally I've had discussions about class structure by drawing class name + methods on a whiteboard but having the same discussion using Visual Studio's UML projection was just as effective.
If you're creating diagrams with graphvis, you're just coding on another language. The benefits of diagrams appear when you draw them by hand (or graphically by mouse).
I generate them: initially with my own generator (which is copyright an employer from > 15 years ago), on a later project I found that Doxygen can do do that for you out of the box :-)
For interactive discussion I just use Visual Studio's projection, for databases I use the SQL Server Management Tool ERD projector or pgAdmin if I'm using Postgres.
this phrase caught my eye, "minimally viable level of detail", to which I immediately thought "minimal detail for a coherent thought". That's a cool concept actually I might hold on to and develop.
> The only reason the other diagram types fell out of favor is because of the development methodology change starting in the early 2000s. The industry started rejecting Waterfall, early design and system architects, in favor of Agile, just-in-time design and empowering developers.
I dunno, whenever I heard people say they're doing Agile all I see is them doing Waterfall without documentation.
"we are lazy assholes who can't keep docs up to date, therefore docs are useless"
Is essentially the argument i see over and over again. And every time i start a new project and that project has docs or uml or whatever I appreciate it. Even if it is a bit out of date, it's way better than nothing.
In my opinion, every project should have a readme file with instructions for running the project locally, and ideally also a high level visual representation of the system.
It should be separated into sub systems/modules for separate functionality and each module could have it's own set of readme and high level visuals. In addition, modules should have small coupling points, typically interfaces and these should have documentation comments describing what they do, inputs, outputs etc. APIs should have something like a swagger doc.
> It's not a question of laziness, it's just that people don't do it so you need automated tools to do it for them
Sounds a lot like laziness to me. It may be more accurate to say it's because people don't care. I've seen projects full of typos. Ive seen projects where basically everything had been duplicated not once but twice because they wanted a slightly different version of the same website so instead of adding some configuration or otherwise finding a reasonable solution for it they just went and copied hundreds of files and prefixed their names before making a couple minor changes and leaving the mess for someone else to discover. No mention anywhere of the fact that this had been done, nor why.
These are the actions of people who don't give a shit. Whatever problems they create are someone else's problems. The way i see it, if you care about your work you'll make sure the code is readable, well documented and so on. If you don't, you won't.
> "we are lazy assholes who can't keep docs up to date, therefore docs are useless"
Rather: managers do not highly value work on documentation, so many programmers care little about it. If writing good documentation was valued more by managers than implementing feature stories, the situation would be different. Incentives do matter.
We are the engineers. It is up to us to tell non technical managers what's important. They don't know shit, they're just there to handle the shit we don't want to handle, like talking to clients or upper management or whatever.
It's all just bad excuses for not doing work properly. Writing clean and well documented code very quickly becomes faster than writing a tangled undocumented mess.
> Most developers IME actively reject these diagrams because they are quickly outdated, or require constant changes to keep up to date
Plans are useless, but planning is indispensable. The act of diagramming things up front is useful to get you thinking about the problem space and come up with the outline of a solution. After that, keeping the initial design documents up-to-date is optional, and often might not be necessary.
During the prototyping phase diagrams do help, but they're usually sketches written on paper or whiteboard. You don't want to waste time with tools and strict specifications to design perfect diagrams, mostly because the design will change frequently, and you don't want your tools getting in the way.
Later on, once the design has settled down and maybe once development has started, those initial diagrams are mostly worthless, but you _do_ want neat and professionally done design documents that describe the system. This allows you to share them with coworkers, and quickly onboard other developers to the project. Hopefully by then the design won't change frequently, which would make updating these a chore.
UML was (and still is) really useful when embarking on a greenfield design. Most people I've worked with know some basic UML notation, so when it comes to whiteboarding and refining the design, it makes sense to go with that.
In terms of artifacts for future maintainers? Maybe not as helpful. As previous posters have mentioned, the diagrams go stale very quickly if the engineering department isn't disciplined about keeping documentation up to date. But this is true for any documentation.
Some diagrams (class and activity, in particular) are less valuable as time passes. I can get the idea of the class structure by just looking at the code itself. The class diagram just ends up being a stale representation of the code.
It is unfortunate that UML has developed a reputation as being overly complex. Now I see more ad-hoc diagrams being created, with whatever notation/symbols make sense to author, rather than using a common diagram system that can be read by many.
> Class, component, package, activity and state machine diagrams are all useful ways to model the structure and behavior of a system visually
They're not bad, but the C4 model is a much better approach to high level modelling (while you can still use class diagrams on the lowest level). https://c4model.com/
We also moved to framework heavy development where you write classes that plug into frameworks. So a POJO here and a POJO there… (everywhere a POJO) that are managed by a framework and exist only to extend the framework are marginally useful. A UML class diagram for a Spring Batch transformer that’s cobbled together from an existing CSV reader component, just isn’t that interesting or necessary.
Maybe UML can find a new life with ChatGPT. Maybe it can fulfill the promise of generating code out of diagrams. UML seems like a fine way to organize prompts.
Does anyone else find the agile way of doing things just ends up with lots of increments and no big picture of how the system should be or where it should be going? There also seems to be a with with waterfall that it's a one way process and you can't do iterations.
> The industry started rejecting Waterfall, early design and system architects, in favor of Agile, just-in-time design and empowering developers. So we saw no need for these visual design tools to model the entire system, since we ended up changing the design during the lifetime of the project anyway.
It wasn't also visual design tools that Agile killed. Agile killed design documentation altogether.
With Agile, today's problems are addressed on tomorrow's sprint, and changes in software architecture take place only in the code. Any effort to document the system architecture in any remotely rigorous way is quickly deprecated, and teams simply don't waste time maintaining something that might already be deprecated once they finish editing the document.
> Contrary to our expectations and previous work, the majority of sketches and diagrams contained at least some UML elements.
I don't have access to the paper, but I can't shake the feeling that those "some UML elements" were boxes with class names in them or something like that.
University in the late 2000's was teaching UML and out of all of the different diagrams and notations, sequence is the only one I have consistently used since then. The rest of the diagrams felt like they mostly were used in big design documents that stopped being written as agile (or a bastardized form of it) permeated more and more organizations.
On a related note, I've found that GPT4 is surprisingly good at building basic sequence diagrams, either based on a description or for open-source projects. E.g.
* "Write a MermaidJS sequence diagram showing a banking application's interaction between a customer, authentication service, business logic, and database"
* "Include database transactions in the sequence diagram"
* "Include OAuth in the sequence diagram"
Or for an open-source library:
* "Write a MermaidJS sequence diagram showing a CRUD Flask application"
* "Include actual function names of the Flask and SQLAlchemy API calls"
426 comments
[ 3.3 ms ] story [ 277 ms ] threadFundamental Modeling Concepts http://fmc-modeling.org/
Used consistently it really helps a lingua franca across teams. Which was the UML aim all along, but it got caught in into "Enterprise Bloat" (like SOAP or XML)
It is one of the few (only) diagram types that is easy to draw and fairly close to the real world implementation. Most other formal approaches are wonky abstractions that only true practitioners can make sense of.
I do really wonder why UML is still taught in universities, as the article states, it's pretty useless. I took a masters Software Engineering course at Georgia Tech two years ago and a big part of the class was learning UML. That time was mostly wasted as I've never used any of it and never met anyone who has used it.
It wasn't my first time learning it either, we also had a section on it in my undergrad software engineering course. So I learned the same useless stuff twice.
- For the university, it fills out offerings and takes up credit hours, keeps the tuition dollars flowing
- For the teacher, it's something they already know how to teach, so it doesn't require nearly as much effort to teach as something more useful but maybe less familiar
- Universities are trusted with the decisions of what to teach and don't face much short-term accountability, so there's no real downside to teaching a useless course for another year
- They probably don't know it's useless. (They also don't care to find out because of the aforementioned points)
- University professors who remain exclusively in academia missed the rising tide and teach what they know
Granted, UML is not used hardly anywhere, but I must've learned 30 different specific software tools in college that I never used outside of college. However, I've used something like each one of them. I took a technical drawing class in high school and I still use some of the techniques I learned in that, even though absolutely no one uses t-squares, triangles, and actual paper in modern technical drawing today.
There's a fair argument re: how much planning and conceptualizing should be done ahead of starting the Agile process, and also a fair argument re: what that planning should look like (crude flowchart? UML-compliant class diagram?). But in rejecting the UML tool, are we rejecting also the idea of advanced planning too? Like, how completely do you need to reject advance planning that it takes the Agile loop to reveal that the customer actually needs software that uses an observer pattern?
My department profs actually got in a bit of trouble with the university because they took the course that they should use for undergrad/graduate mentoring (something like a "special studies in XXX" placeholder, usually for independent or small group study that was special enough for course credit) and used it to create their own courses outside the review of approving a new course with a distinct number and credit count.
The reason they did it in the first place was because if they wanted to change the curricula for the existing courses, remove course numbers, or create new ones, the bureaucracy would take 4-8 semesters to get approval and complete. By which time some of the material was obsolete. One of the profs got fired and the rest quit, eventually.
So it is well worth 1 hour or 2 to look at it.
Before UML, it's hard to capture the state of corporate software development that allowed the insanity to take part. I mean, UML was the marriage of two different approaches to drawing object models that were locked in a battle: OMT and Booch method. There weren't tons of open forums for discussion and debate like the internet has now, there were conferences and such and these guys were basically trying to create formal methods for objects in a vacuum.
It was kind of existential stuff for a lot of the smaller players in the industry, everyone saw value in this newer approach to building software. "Reusable components" seemed huge. Tooling was expensive, training was expensive. Microsoft was moving as a scary rate, connect your cart to the wrong horse and it could cost you the company... On some of the usenet forums, about the most open discussion there was at the time, I read debates about the virtue of C++ style multiple inheritance vs single inheritance and there were product matrices for programming tools that had check boxes for crap like that. C++ and CLOS both supported multiple inheritance so to the casual observer they were "better." Now I've never seen serious industrial software written in CLOS or anyone even considering it but it "had the features." It was just a different and crazy time, kind of amazing how open source/free/libre has altered things, the entire culture of building software is different and probably more healthy.
Anyone want to shit on design patterns next?
Without those various perspectives, you end up with students learning all kinds of goofy things just because no one said, nah, they’re probably not going to need that.
Does that mean something? Besides you saying you worked in them? It’s a question ; I don’t know.
yep. kids out of college feel most inclined to use it.
If you have a project document template from PMBoK, do you feel obliged to fill all the sections or you document only information relevant to your project? With UML it’s the same: it offers a lot, but you do not have to use everything to produce a conforming diagram.
Note that, for many of these diagrams, they existed before UML. It was an attempt to formalize them. In classes, they are often used as code generation tools in an attempt to keep a 1:1 between document and code. Laudable, but I have yet to see that work out well.
To your point, I think, the same ultimately goes for document templates. Way too many are used prescriptively as a way to make a successful project. Much to the chagrin of the document writer when the project fails. Often miserably. To the point that I'm convinced most accurate project documents are after the fact. Certainly not waterfall to the project that they are describing.
I suspect that's true: teams with a very immature engineering culture probably do use a lot more UML. It's a good way to feel like you're doing something useful instead of actually doing the hard part. Mature teams write code.
Sounds very Dunning-Krugerish “smart people like me do X and not smart people do Y”
Coding and documenting aren’t exclusive. Modeling is part of documenting. UML is a type of modeling.
I would think effective teams will want to build good software. And to build good software they’ll want to capture requirements, communicate with other teams, and test their software. Design helps with this and is part of coding.
At the end of a successful day, I should have some updated models, some code, and some running software. If someone wants to see what I did, they’d likely read through different parts.
Just like trying to figure out a stage by just reading models sucks, so does trying to figure it out by just running the software.
Other forms of documentation have their own tradeoffs, but I was not discussing those. You're the one who automatically equated UML with all possible documentation.
> to build good software they’ll want to capture requirements, communicate with other teams, and test their software
UML is awful at all of this.
> At the end of a successful day, I should have ...
> “smart people like me do X and not smart people do Y”
You don't see the irony here?
I also don't think the UML variant of state machines and workflow are any popular. But well, there is probably somewhere where people use them. Also, those lists usually ignore entity-relationship diagrams, where UML just adopted the popular format (without even minor changes, like for workflows), and thus everybody uses the UML one.
But yes, people don't remember about deployment diagrams. Those are used a lot.
Computers are much better at this kind of checks anyway, and they don't need diagrams.
1 - Instead of "well, maybe it's possible despite I never seeing it"
Not every artifact is worth keeping, instead the value can come from the process of creation as a way to structure your thoughts or to explain or brainstorm possible solution. The value of class diagrams for those people is in the moment and it’s ok to throw them away later if they become useless.
One powerful aspect of UML is that you can combine different diagram types. For example, you can use activity-diagram elements in parts of a sequence diagram.
For pragmatic use, “UML Distilled” [0] by Martin Fowler is a good introduction and reference.
[0] https://martinfowler.com/books/uml.html
So here's the conflict: if we agree that planning is good, communication is good, and that it is faster / cheaper to design before we build rather than rushing in to build something, then is it not a good idea to have something like UML in our tool kit? Perhaps UML was too complicated or overbearing, but I've always felt like a universal tool to describe aspects of the software we are building is fundamentally a good concept. Further, it feels like the right idea to document / designing up front in a way that increases buy-in and communicates what we are doing.
So if not UML, then what?
I'd argue the issue is that because UML is not seen as valuable, everyone improvises their own dialect when drawing stuff, and so since nobody trusts people following correct diagram semantics (e.g., meaning of different arrow shapes), nobody trusts the resulting diagrams either, further reinforcing the notion that it's useless.
One trend/fad was to put words describing links between tables, but I usually didn't find such helpful. Maybe if the wording was done well it would help, but most seem forced in practice. Good naming takes experience. Maybe let newbies draft the phrases, but have someone with experience review it. I.e, mentoring.
Self-documenting code/schemas are an even better place.
...sometimes I feel like I'm the only one in the world who uses DB-level metadata (e.g. `sp_addextendedproperty` in SQL Server) to attach explanatory notes and other metadata to database objects, including columns and constraints - and it gets better because I modified my Entity Framework scaffolding templates to then include those comments in the generated C# code as XML-doc (or JS Doc comments in TypeScript) - and the entire DB schema is also kept in source-control (using SSDT).
Additionally, because CHECK constraints in SQL are declarative it means I don't need to write-up a human-readable explanation of (for example) the format restrictions based on a column in the CHECK constraint, because it's immediately visible and obvious (and yes, my scaffolding templates also include the CHECK's expression in C# code-comments too for-reference).
----
Another technique I'm a huge fan of now is using predicate-types (similar to dependent-types) by taking advantage of class-invariants: so I have my own zero-overhead (i.e. elided structs) like `NonEmptyImmutableList<T>` which immediately lets everyone know that if that's passed as a parameter then it won't ever be empty - whereas if the code used the stock `List<T>` or `IReadOnlyList<T>` types you'd have to write-up how that list should be used - which no-one should have to do.
I just lament that my daily-driver languages (namely C#) make it kinda tedious to define types like that.
I've used it for years - usually auto-populated from the model that builds the relational schema (like you had done). Same for constraints. By coincidence, I just convinced my team to start using sp_addextendedproperty.
That's the advantage of using a higher-level notation, such as UML or code-first EF, for your ORM.
Good idea on the C# type naming conventions.
But they don't offer enough columns and detail for certain things in my experience. A shop-rolled data dictionary can be "shaped" like shop needs.
The problem with UML is that the industry went overboard with it's usage, like it did with pretty much every tech trend.
Another useful chart type provided by Mermaid.js is the git diagram, which I use all the time when brainstorming change processes, especially for other folks who might not be git-conversant.
https://mermaid.js.org/syntax/gitgraph.html
Out of these text-to-diagram tools, D2's syntax seems the friendliest to me. See https://text-to-diagram.com/.
One thing that worries me is that the profusion of text-based graph description languages will result in a family of software that's unparseable due to its success. We have Graphviz, GNUplot, PlantUML, BlockDiag, Mermaid, Kroki, Vega, and too many others to count - but we don't have a Pandoc.
In Greek mythology, the goddess Pandia or Pandeia was a daughter of Zeus and the goddess Selene, the Greek personification of the moon.
> The most common failure mode for sequence diagrams is over-complication. (This also is the failure mode for most diagrams, as I wrote in an article on flow charts).
Agreed.
UML – with the goal of being a graphical language for _complete_ specification of a system (both for code generation as well as to have diagrams generated from code introspection) – has to be exhaustive, therefore fails at showing the big picture.
Use of UML that could accommodate multiple levels of abstraction would fix that. I believe this is what C4 [1] tries to achieve with 4 levels of diagram. Unfortunately everybody who invents a new diagram model also reinvents the wheel and throws the entire UML away. One could easily use UML visual language, but just standardise on using the 4 levels diagrams of C4.
[1] https://c4model.com
As a graph model, FBP lets you fan out widely, but that is something you don't actually want to do most of the time: the benefit I am seeking it out for is in the bounded buffers adding backpressure regulation and debuggability. As such I've currently settled on mostly defining ports in terms of structured data types, then doing destructuring/merging/splitting in custom processors.
But even when I was working on more distributed systems, I found more value in state machines and simplified class diagrams, actually. I think most cases where you're using a sequence diagram, a state machine is a better tool. Both for thought, and for implementation. Surfacing implicit state machines can require some extra upfront design, but if you have a non-trivial amount of states, it's pretty much guaranteed to be worth it.
When managing to get that right they are great, otherwise you get loads of edges...
[1] https://statecharts.dev/
Statecharts - A visual formalism for complex systems. David Harel. 1987
https://archive.org/details/7.-statecharts
Looks like you can also freely download the paper from here: https://www.sciencedirect.com/science/article/pii/0167642387...
The only reason the other diagram types fell out of favor is because of the development methodology change starting in the early 2000s. The industry started rejecting Waterfall, early design and system architects, in favor of Agile, just-in-time design and empowering developers. So we saw no need for these visual design tools to model the entire system, since we ended up changing the design during the lifetime of the project anyway. The drawback of this, of course, is that with the Agile approach these diagrams never end up being made, so developers are left to assemble their own mental model of the system, which hurts the overall comprehension. Most developers IME actively reject these diagrams because they are quickly outdated, or require constant changes to keep up to date, which is true, but this is not unlike documentation, comments, and a myriad other things that needs to be synced with the code.
Yet sequence diagrams are useful in a wide variety of use cases, and let's face it, they're the easiest ones to comprehend, and are even understandable by a non-technical audience. In contrast to the other UML diagram types that have strange notations and the information is more densely packed.
I completely agree with you.
It's a good way for other people to present information, for me to look at.
I just won't do it myself.
It's not only me; and that's why it's dead.
I won't do it because the first thing that comes to mind is how it will go out of date in a month, and have to be maintained to stay accurate.
Maybe in the not-too-distant future we will have AI grokking large code bases and cranking out accurate, useful, UML diagrams out of it.
All those diagrams, when they are complete, correct and up-to-date, do convey what they are supposed to convey.
I used to whiteboard for this, but that hasn't carried over well in the remote world. What I miss about whiteboarding though is that you can tell a story as you draw, so whoever's viewing can watch something unfold from a blank slate while I'm walking them through the history of whatever system we're describing. That said, I can make a PlantUML diagram much more correct than a whiteboard.
All that said I too would love for more of that to be automated increasingly through AI. And I suppose it should make sense conceptually, because for me the value of a crafted diagram over an automated one is that no one really wants to look at the insane ERD of an OLTP database or a production object model. They want the digestible high level vision of the important bits, or the bits that are relevant to the conversation taking place. So it's a summarization problem. How to get the right data to produce a correct summary is interesting--I'm sure if I look there's a dozen papers to read on a similar subject :).
> All those diagrams, when they are complete, correct and up-to-date, do convey what they are supposed to convey.
I spent a bit of time prototyping this recently. It's definitely possible. Rational Rose also had the capability to generate diagrams from code though. I don't remember how good it was at the task though. Was Rational Rose just a very bad implementation?
I find the hate in this chat strange because diagrams are incredibly useful when working through complex problems* and then conveying that information to other engineers. My experience over 20+ years is that a huge portion of engineers can't grok complex problems from code alone.
*Most of my projects are optimizing billion+ row databases, micro-service architectures, and various other scaling challenges.
Where those boxes are in relation to each other matters. You can't just randomly throw boxes and lines on the page, you need to arrange them so that boxes that we can tell what things are related by how close they are to each other. Automatic UML doesn't capture that.
Sometime you have complexity in code that needs tobe hidden by default. I don't care about rare error cases most of the time, but automatic UML can't know what is the complexity needed for rare cases and what is complexity you need to show the junior on the first day.. related to this when i'm interested in one error path how do you hide the others?
Then the real killer of both. Next week there is a minor requirement change (new features we always knew were coming and planned for even), and now the code changed. UML doesn't follow that. Either you generate UML and have the above problems. Or you manually update UML in theory, but in practice just let it slide as the week after you know something else will change and you don't nees it today anyway.
I've heard this argument many times, but how is it different from keeping documentation, comments, tests, or the issue tracker up to date?
They all require some discipline, but if the team finds value in any of these things, they would make an effort to keep them synchronized with the code.
Besides, I suggest not falling in the trap of having formal design documents early on in the project's lifetime. Rather start with informal diagrams and sketches, and once the design has mostly settled, switch to something like UML. This would mean it wouldn't require changes every other week.
As for automatically generating, and dynamically arranging diagrams, this is more up to the generating tool than UML. These tools are still stuck using decades old technology at this point AFAIA, but there's no reason that a smarter tool couldn't do the things you mention.
I would kill for a tool that could output class and sequence diagrams from a project or component. If the format is editable and tools can automatically layout/filter out components, all the better. Right now the main time sink in putting together diagrams is trying to express what's in the code. Once that's in place, we can prune stuff we don't need.
Moreover, I think comparing different UML diagrams can also be enlightening for university students. E.g. state machine digrams look quite similar to activity diagrams, but the former emphasize states and the latter actions. And class diagrams let you learn the connection between class structures of OOP languages and database structures.
UML lets you visually learn the abstract higher level concepts without having to rely on irrelevant specifics of practical implementations, or just on dry theoretical text.
It most certainly is not.
This is clearly better than UML. UML is full of shorthands that nobody remembers. That's worse than people making labelled custom diagrams.
Here's an example:
https://buck2.build/docs/concepts/concept_map/
Imagine how much worse that would be with UML arrows.
I agree on the "shorthands", like empty/filled arrows, that people may not know. But there isn't much alternative to such shorthands other than leaving them out completely, which wouldn't be an advantage. In diagrams some information is either conveyed succinctly or not at all. The "alternative" is a block of text instead of a diagram.
> People who say "UML is useless" basically say "diagrams are useless".
Starting with UML to describe a set of classes or - worse yet - an entire system is lunacy and a massive red flag.
As said, the sequence diagram is a real plus because sequence information is not very well expressed by code, so that diagram has much added value.
I personnaly find UML hard to use becaues if you want to communicate your ideas precisely, you have to know much of its formalism and most often, people who read your drawings don't master its intricacies, so communication quality is no good...
Code can be formal enough but in reality it is almost never formal enough. Many constraints can be expressed imperatively (eg. someone validates the number of related objects in the create view) and in unexpected places (across repositories and libraries and maybe not even in code but in some stored procedure). And then it is all in flux and can go away the moment you change your stack.
I don't know if UML is perfectly flexible (maybe?) but its sure benefit is a source of truth that does not depend on your implementation.
There a diagrams that are useful before coding, but most of them aren’t part of UML, which is a product of the simultaneous highwater of class-based-OOP-is-everything and pre-Agile industrial software development methodologies, and (except for some isolated bits) poorly fit to anything else.
I don't think this is right or a well founded opinion. The whole point of any diagram language, including UML, is to provide the means to describe software projects in different views, including class diagrams but also component and system diagrams.
What do you think is the whole point of a modeling language?
Sometimes motivations are misguided, and sometimes instances aren’t well fit for major motivations of their broader class.
You, and OP, failed to present a single argument supporting the thesis that modeling languages in general, and UML in particular, are "lunacy and a massive red flag."
> Sometimes motivations are misguided (...)
Not only did you failed to support anything in the original anti-diagram rant, now you also tried to support generalizations with hypothetical corner cases involving misuses, which is an absurd argument to make.
So not only do you have zero substance for show with regards to the original anti-UML rant, you also resort to using vague, unsubstantiated strawmen.
This is to be expected. Like many discussions involving technical aspects, generally detractors come from positions of opinionated ignorance.
I failed to support that thesis because I never endorsed it. Pointing out a flaw in a counterargument is not endorsing the argument it is deployed against.
Not building an entire system down to class level which is what it is all too often used for (in my experience exclusively by people who have never and cannot code).
It's inefficient, doesn't play well with Software Engineering (diff, version control etc..) and is a relic of the past.
Keep the classes in code, project that into a diagram for the few occasions that is actually needed, and stick to a simplified tool like C4 (https://c4model.com) for your architectural views. Sprinkle some sequence diagrams in too to help describe the key data flows (they're handy next to C4).
Why use C4 over UML? Because the vast majority of the audience don't even know what UML is. So keep it extremely simple and include a key / guide to any of the (few) shapes or colors you use so that it's completely self contained.
The vast majority of UML belongs to be put into the Indiana Jones storage facility along with other archaic ideas such as Function Points / Function Point Analysis.
That was never the point of modeling languages.
Your baseless assumption is even more absurd when you factor in the fact that modeling languages even express runtime behavior, componente, and packaging.
The main problem with these mindless attacks on modeling languages in general and UML in particular is that the bulk of their retractors clearly knows nothing nor has any direct contact with them, or how they are used in the real world. Their arguments are nothing more than poorly thought through strawmen. Your comment fits well.
> Why use C4 over UML?
See, this is a telltale sign you know nothing about what you're commenting on. Not only is C4 a modelling language like UML but it also covers the exact same responsibilities and features of UML. C4's main selling point is advocating for the representation multiple points of view, and UML is a standard specification to express all the points of view you see fit in a coherent and rational way. There is no C4 vs UML. They have both the exact same design goals and usecases.
Also, class diagrams are more useful when you can’t give out source.
That being said, I think you can autogenerate class diagrams from code so it’s not like you should spend a lot of time making them.
However I sometimes find them useful to extract key parts of the system and showing their interaction. Cutting away many attributes, many helper classes, many other things.
That can lead to pictures which are quick to grasp and then allow further digging based on code.
High level boxes are great for thinking about systems but the key there is abstraction - minimal viable level of detail..
That discussion is almost never going down the the level of an individual class and NEVER adheres to the UML standard.
Very occasionally I've had discussions about class structure by drawing class name + methods on a whiteboard but having the same discussion using Visual Studio's UML projection was just as effective.
For interactive discussion I just use Visual Studio's projection, for databases I use the SQL Server Management Tool ERD projector or pgAdmin if I'm using Postgres.
Those are a different kind of diagram than the one you create from scratch to decide what goes in the program.
I dunno, whenever I heard people say they're doing Agile all I see is them doing Waterfall without documentation.
Is essentially the argument i see over and over again. And every time i start a new project and that project has docs or uml or whatever I appreciate it. Even if it is a bit out of date, it's way better than nothing.
In my opinion, every project should have a readme file with instructions for running the project locally, and ideally also a high level visual representation of the system.
It should be separated into sub systems/modules for separate functionality and each module could have it's own set of readme and high level visuals. In addition, modules should have small coupling points, typically interfaces and these should have documentation comments describing what they do, inputs, outputs etc. APIs should have something like a swagger doc.
I used to hear people say the same thing about laziness about code style before reformatting/linting tools became standard.
Sounds a lot like laziness to me. It may be more accurate to say it's because people don't care. I've seen projects full of typos. Ive seen projects where basically everything had been duplicated not once but twice because they wanted a slightly different version of the same website so instead of adding some configuration or otherwise finding a reasonable solution for it they just went and copied hundreds of files and prefixed their names before making a couple minor changes and leaving the mess for someone else to discover. No mention anywhere of the fact that this had been done, nor why.
These are the actions of people who don't give a shit. Whatever problems they create are someone else's problems. The way i see it, if you care about your work you'll make sure the code is readable, well documented and so on. If you don't, you won't.
Don't forget that some details shouldn't be in UML.
Rather: managers do not highly value work on documentation, so many programmers care little about it. If writing good documentation was valued more by managers than implementing feature stories, the situation would be different. Incentives do matter.
It's all just bad excuses for not doing work properly. Writing clean and well documented code very quickly becomes faster than writing a tangled undocumented mess.
Plans are useless, but planning is indispensable. The act of diagramming things up front is useful to get you thinking about the problem space and come up with the outline of a solution. After that, keeping the initial design documents up-to-date is optional, and often might not be necessary.
During the prototyping phase diagrams do help, but they're usually sketches written on paper or whiteboard. You don't want to waste time with tools and strict specifications to design perfect diagrams, mostly because the design will change frequently, and you don't want your tools getting in the way.
Later on, once the design has settled down and maybe once development has started, those initial diagrams are mostly worthless, but you _do_ want neat and professionally done design documents that describe the system. This allows you to share them with coworkers, and quickly onboard other developers to the project. Hopefully by then the design won't change frequently, which would make updating these a chore.
In terms of artifacts for future maintainers? Maybe not as helpful. As previous posters have mentioned, the diagrams go stale very quickly if the engineering department isn't disciplined about keeping documentation up to date. But this is true for any documentation.
Some diagrams (class and activity, in particular) are less valuable as time passes. I can get the idea of the class structure by just looking at the code itself. The class diagram just ends up being a stale representation of the code.
It is unfortunate that UML has developed a reputation as being overly complex. Now I see more ad-hoc diagrams being created, with whatever notation/symbols make sense to author, rather than using a common diagram system that can be read by many.
They're not bad, but the C4 model is a much better approach to high level modelling (while you can still use class diagrams on the lowest level). https://c4model.com/
It wasn't also visual design tools that Agile killed. Agile killed design documentation altogether.
With Agile, today's problems are addressed on tomorrow's sprint, and changes in software architecture take place only in the code. Any effort to document the system architecture in any remotely rigorous way is quickly deprecated, and teams simply don't waste time maintaining something that might already be deprecated once they finish editing the document.
Sequence diagrams are awesome. The rest of UML (and all the crazy Rational Rose nonsense!) was so much angst over such petty things on notation.
And then there is the dumpster fire called Enterprise Architect…
I don't have access to the paper, but I can't shake the feeling that those "some UML elements" were boxes with class names in them or something like that.
* "Write a MermaidJS sequence diagram showing a banking application's interaction between a customer, authentication service, business logic, and database"
* "Include database transactions in the sequence diagram"
* "Include OAuth in the sequence diagram"
Or for an open-source library:
* "Write a MermaidJS sequence diagram showing a CRUD Flask application"
* "Include actual function names of the Flask and SQLAlchemy API calls"
* "Add a redis cache"