Handling edge cases in flowcharts without blowing up the entire diagram
Posted by Sad_Translator5417@reddit | ExperiencedDevs | View on Reddit | 21 comments
Working on some complex system flows and running into the classic problem where edge cases and error handling paths are making my diagrams unreadable. The happy path looks clean but once I add all the exception handling, timeouts, and edge cases, it is tangled up.
Any strategies for keeping flowcharts maintainable when we need to document all the messy real-world scenarios? Thinking about layered approaches or separate diagrams but curious what's worked for others.
Aleks_Zemz_1111@reddit
If you try to map every single edge case, you've stopped being an architect and started being a Busy Fool.
I spent years doing roofing and construction before I ever touched a computer. In roofing, you don't draw a flowchart for every possible way water might leak. You just follow the pitch of the roof. If you spend all your time documenting the what-ifs, the rain has already ruined the building before you've even started.
Right now, my day job is packing rolls of paper into boxes. If we had a manual for every possible way the tape gun could jam or the cardboard could rip, the line would never move. We'd be too busy reading the Flowchart of Failures to actually ship anything.
Your diagram is bloated because you're trying to solve problems on paper that should be solved in the code's error handling. A flowchart is for the Happy Path. That’s it. Anything else is just noise that makes the real system invisible.
Delete every Timeout and Exception box from your main diagram. Replace them with one single box at the bottom called "GLOBAL_ERROR_HANDLER." Move the messy logic into a technical doc or a simple table.
If you can't see the Success Path from across the room, your diagram isn't an asset, it's a distraction. Stop acting like a janitor for edge cases and start acting like the guy who keeps the line moving.
Smart-Razzmatazz8668@reddit
reminds me of the time i tried to do something similar and it backfired
Excellent-Average782@reddit
Are you having a layering problem or a complexity problem? Most of the time that's the case. What has worked for me is using Miro flowchart to physically space happy-path flows left to right, while edge cases branch downward into their own zones.
Visual separation by direction sounds simple, but your brain reads them as genuinely different concerns. Exception flows stop fighting for attention with the main logic and the whole thing becomes readable.
Sad_Translator5417@reddit (OP)
The physical separation is a good idea. How do i ensure i don't have a million diagrams for the edge cases?
Veuxdo@reddit
A sequence diagram for each important thing a system does isn't really that crazy. If it does 100 things (if you include exceptions as "important"), then 100 sequence diagrams is probably in order.
Of course at that point you probably want tool that allows sharing resources between diagrams (a "model-based" tool).
Sad_Translator5417@reddit (OP)
Thank you for breaking it down
iKnowNothing1001@reddit
The tangled diagram problem is almost always a layering problem
Sad_Translator5417@reddit (OP)
Had not thought about it that way
kenwards@reddit
I know AWS literally publishes separate runbooks just for error handling, the same logic applies here. The main flow stays clean and exceptions live in referenced sub-diagrams.
Sad_Translator5417@reddit (OP)
That's the kind of model i was hoping to replicate
GoodishCoder@reddit
For me it depends on the audience and the outcome I want. For a lot of diagrams I don't include application level decisions if the audience is other developers. My expectation is that developers handle exceptions at the application level. When documenting the business process I include error paths but will group as many errors into the same path as I reasonably can with the requirements I have.
Personally I believe flow charts should be super simple so trying to catch all of the edge cases doesn't make sense to me.
Sad_Translator5417@reddit (OP)
That's a good one. I'll try to simplify my flowcharts as much as possible and group my error paths.
pablosus86@reddit
Try to keep the same level of detail. I've found myself putting more details into error paths to define the scenario, but that level of detail isn't in the main path so it's not apples-to-apples. I like multiple diagrams. A higher level one with the main flow, the critical points, etc with "see Exception A" type stuff, then subsequent diagrams with more details. Including a happy path with more details too.
Sad_Translator5417@reddit (OP)
Do your detailed happy path diagrams live separately or stay linked directly to the high-level one?
pablosus86@reddit
Ideally in the same document but it depends on the exact format. The key is that if you're looking at one there should be no doubt about how to see another.
Sad_Translator5417@reddit (OP)
I appreciate the insights
blekibum@reddit
Treat errors like footnotes, not main content. Color coding alone won't save you once complexity hits a certain threshold. Separate canvases with clear linking conventions is the only thing that scales.
Sad_Translator5417@reddit (OP)
I have done my best to ensure there is separation so far
blekibum@reddit
Whatever you use, it will be easy to clean up the mess with that
Ill-Education-169@reddit
In the past, we have made “tabs” with messier types.
In the flowchart you could express a happy path and then Exceptions would be defined but when it gets messier, you put something like “see Exception A”(being a new chart/tab).
Also making sure all of these are well documented helps avoid mis understandings and agreement on business logic for the org/stake holders.
Sad_Translator5417@reddit (OP)
That "see Exception A" pattern sounds like something worth trying.