As someone who's self-taught everything, this is... awesome. It's exactly what I needed to be able to up my game in describing code to management using the flowcharts they've asked for.
In case you haven't gleaned it from the majority of comments here, flowcharts are a terrible way to describe code, particularly modern, multi-threaded code that uses exceptions. Don't go there.
I quite agree. Unfortunately management wants single-threaded code and wants it documented with flowcharts. So right now there's lots (!) of clouds detailing "this calls into another API documented in another flowchart..."
To me, that screams "put your resume out on the street".
I mean, I'm not opposed to documentation. It's important. But if your management thinks that flowcharts are the way to do it, I wonder what millennium they think it is.
Indeed? Flowcharts aren't the only documentation. Swagger describes the API parameters, flowcharts describe the API code flow, and text provides a story, and comments in the code describe particulars.
Flowcharts are just where I've felt that I've significantly underperformed; where management has asked for more of them.
Putting my resume on the street is something I do often. Want to look at it?
If you think flowcharts aren't the way to describe code flow, then I'm curious what method you think is better.
Ah. Flowcharts were all you mentioned, so I assumed (bad move) that they were all you did.
Depending on what exactly you are doing, parts of UML might be better. It lets you describe different aspects with different diagrams, so that, if one kind of diagram is sub-optimal for showing some aspect of what's going on, another kind might be better.
This is because flow charts are two dimensional. What you need is a 3rd dimension to represent parallelism. These programs are better represented as 3d structures rather then 2d flow charts or even text.
The closest I've seen to anything that actually does that is UML. But it does so only by having multiple different diagrams. That's like having a drawing with a front view and a side view - it's not a 3D diagram, it's two 2D diagrams that you can use to kind of see what's going on in 3D.
I don't know of any good system of notation that does what you're asking, nor any software for drawing or viewing such diagrams. But I agree that 2D flowcharts don't represent parallelism well, and that 3D looks like a better answer.
UML is non-rigorous and has a whole lot of pointless incidental complexity. Intuitive representations of parallelism are fairly natural in data flow, but that is precisely dual to flowcharts; you can not represent both on the same 2D diagram without some very precise rules about what portions of the diagram are intended to represent each. Proof nets give you something not unlike this.
Oh, I never said UML was ideal. I merely said that, if you squint, you could see it as a clumsy, inadequate, and probably unintentional half-step in the direction of crimsonalucard's idea.
If you find these flowcharts instructive, and I think that you are well founded in doing so, good on you. A majority of other comments seem to be of the opinion that pointing out the complexity of control flow generated by the constructs in a language is a negative. It certainly seems like the prevailing attitude is ‘if I can’t see it, it doesn’t exist.’ But you said you were working on game code, so I will encourage you to keep thinking about the complexity of the choices you make in which constructs to use and don’t buy into the thought that says performance implications are not a really concern.
Actually, I didn't. I said I wanted to "up my game" which is a phrase commonly meaning "to get better". Said another way: I needed to get better at describing code to management.
> I will encourage you to keep thinking about the complexity of the choices you make in which constructs to use
Indeed, management generally wants simpler code even at the cost of performance. Simpler code generally translates to cheaper developers and cheaper maintenance.
> don’t buy into the thought that says performance implications are not a really concern
I actually write DNA analysis software. Performance implications definitely are a concern. :)
But performance is useless if I'm the only developer who understands how it all comes together (eg, high bus factor). So I've been writing a lot of documentation to that end, from file-level down to the systems-level and bit-level descriptions. I really would like better support for diagrams in markdown.