DEV Community

Bertil Muth
Bertil Muth

Posted on

Importance of diagrams

Do you use diagrams in your development processes? If yes: do you draw on the whiteboard, or use an electronic tool? Which language do you use, UML, Simon Brown’s C4 model, or something else? Is the time doing it well spent?

Top comments (14)

elmuerte profile image
Michiel Hendriks

I use UML2-like, and then mostly class diagrams. I do not adhere strictly to the UML2 standard because I think it's mostly flawed to properly convey the design. The class diagrams mostly contains relation information (association/aggregation/etc.), multiplicity, and (some) properties. I only mention properties which are not implied by associations. I don't add methods and accessors. That just adds too much noise. The picture should present an overview which is associated with explicit textual description. As tool I use PlantUML/PlantText.

I sometimes also use flowcharts, although a limited subset. But unlike most people I tried to stick to the "standard". So the flowchart has a start and ends, diamonds for named choices, etc. For this I generally use

I've also used railroad diagrams in case of language/syntax specifications. For this I use the online Railroad Diagram Generator.

I use these tools mostly for documentation usage. On whiteboards I generally just create "boxes and arrows" diagrams.

davidkpiano profile image
David K. 🎹

I use statecharts (and I strongly avoid using the term UML - that encompasses much more and is pretty hairy and overly complex).

I use my own library to create them:
And visualize them:
I highly recommend checking out for more information on why modeling your application via statecharts can be useful :)

cjbrooks12 profile image
Casey Brooks

I love to use diagrams for organizing my thoughts at a high level on a complex feature before writing any code for it. It really helps me to figure out exactly what this new features needs to have and how the various pieces should work. As I get writing code for this feature, it also serves as a great reference, so I can check how clearly the code follows the diagram and that it is doing what I think it should be.

I don't try to be too strict about UML syntax, and when I start writing code, I may find the code requires a different setup, at which point I will modify the diagram to match the new direction.

As for tools, I really like using PlantUML. While its documentation isn't that great, it is a really powerful tool, and I love that I can create diagrams just out of text. I like being able to check a diagram into source control, and it makes it much easier to compose large diagrams. Before I found PlantUML, I always liked the idea of diagrams, but always found graphical diagramming tools clunky and difficult to scale to anything with more than a couple dozen nodes. PlantUML frees me from the layout and allows me to just express my thoughts in terms of relationships among nodes, and it figures out how to draw the diagram so it can be easily viewed at a glance.

There are lots of tools that integrate with PlantUML, but I like to manage my diagrams with Orchid. I originally built Orchid to document my Java projects' code and wikis, and being able to embed diagrams right alongside that makes it really easy to keep up to-date. I even have a project that uses a pub-sub architecture, and I parse the Java sources to find all the places that fire/receive events, and generate a PlantUML diagram mapping out the entire app. I can then compare this generated event diagram with the one I created manually to verify that the actual application structure matches the planned structure.

bertilmuth profile image
Bertil Muth

Yes, I think generating diagrams from code can be really powerful.

functor profile image

And I think in this case, there are some tools that generate architecture diagrams automatically from the source code. Here is what I use for my projects

joshcheek profile image
Josh Cheek

I basically don't use diagrams. Maybe every now and then, very infrequently. I have in the past, once or twice, for ER diagrams (but I really don't do that anymore, either, it's faster and better to just prototype the db schema) or flow between pages for a user or an object model description (purely to explain to others what I've figured out), or a state machine (I might do more of this, if I worked with state machines more frequently). So, yeah, not opposed to them, just rarely ever have a good reason to use them.

juankortiz profile image

Not "using" for my projects, but currently I'm teaching OOP with UML, and we use StarUML for the exercises. It's a simple tool and the free version does the a great "Sublime" impression by poping up a modal every now and then, but it gets the job done.

jillesvangurp profile image
Jilles van Gurp

Not really a thing these days IMHO. I know people used to be obsessed with diagrams and using them as documentation, or worse as part of some hideous model driven architecture monstrosities. I find I rarely consult them these days even if they are available, which in itself is extremely rare.

As for producing them, IMHO time spent on artifacts that don't co-evolve with software produced needs some really strong argumentation for being a distraction from doing that. So, I tend to not waste time on this. Whiteboards are nice but sadly my handwriting has devolved to the point of being completely useless. Pretty much the only time diagrams come up as a thing is when some customer or manager insists on having them, usually for box ticking reasons rather than any practical reasons. Usually feels like an epic waste of time and I've never really observed people getting actual value out of having them.

Besides, you can't really convey a lot of complexity in a diagram so their added value is limited to pretty much stating the obvious. Like, "we have a layered architecture involving a DB, a bunch of servers that talk to each other, etc.".

jamesmskelsey profile image
James Kelsey

I use a whiteboard for broad strokes, then transfer to paper for finer details. I have occasionally used a website that does the Agile thing, and that helps a lot for making/setting goals.

Having a plan on paper, even for the most basic of projects is worth every second. I spend considerably less time fiddling with layout and implementation if I have something written down, drawn, whatever the case may be.

That being said, I haven't done any web development professionally. I can't imagine being successful in a professional setting without having SOME way of expressing the plan to everyone in the team.

alainvanhout profile image
Alain Van Hout

I've also gotten the impression that diagrams are used far less often these days. I myself use them infrequently, if and when they add benefit, and only with the formality that the situation requires.

From a pedagogical perspective, learning how to use diagrams like UML tends to be a great way to expand your understanding and insights into architecture and behaviour flows. They are also a (necessary?) stepping stone to grasping higher-level concepts like design patterns. At some point though, communication can more efficiently be done via those higher-level concepts than through (lower-level) diagrams. This at least in part relates to the notion of Wittgenstein's ladder (wikipedia page).

stealthmusic profile image
Jan Wedel

Not very often. We use use for some very important things like deployment diagram for multiple services and some behavioral diagrams for complex business logic. For that, we use Gliffy in our confluence as a tool, and we draw on windows and white boards in our office. We don’t use strict UML and we don’t call it UML. The main purpose is, that’s the intended audience is able to understand it easily. For the unclear parts, we add a legend. Like, what does green vs yellow box mean, what does the incoming or outgoing arrow mean.
Again, the most important thing is to convey the message.

Sloan, the sloth mascot
Comment deleted
bertilmuth profile image
Bertil Muth

Looks nice. Is there a free/trial version?

imatmati profile image
ivan matmati

Real developers make ASCII diagrams :-). Remember RFC ? Ascii flow