UML's a Thing

I've learned all I know about designing systems, and development overall, just from the hobbyist experience throughout my life. The smallest thing I can owe to others for the blessing of time and ability to learn these things, is to share what I know. This sparse post is about UML. Here's where my development branch is at, structurally -- this diagram will be included with the docs also.

This diagram simply huge, isn't it, and it's making itch.io's WYSIWYG editor flip out!! It was also kind of a PITA to make. UML, Unified Modeling Language, is a visual modeling language. The purpose of the diagrams described by UML is the accurate communication of technical architectures. There are probably standards, I know nothing of this. I research the basics, to try to make sure the diagrams I produce are legible to other people I'm working with, and in this case to the end user.

Experienced developers, and developers who went to school for it, already know about UML. But I'm sure there are those out there who have not gone to school, and are just dabbling as hobbyists. Creating UML diagrams during your design process, or after you've already written hundreds of lines, is a great way to understand what's happening in your code, which is a great way to aid in debugging.

This here is a class relationship diagram. I spent about two hours making that one, based on my existing code base because it's easier for me to contemplate that way. The two hours were well-spent: I understand the code base better, certainly from this I understand better how the classes interact with each other. At a glance I can see that some methods, like NGManager.list_node_handles() might be better off in another class. It made it very clear where I had previously failed to name things consistently (I fixed this, create_handle_data() was just add_handle() ).

I also find the class diagrams useful for making sure I don't botch up the public interface... I've left a note for myself as to which classes will "belong" to the end user a/o v0.8.0.

Another useful tool implemented by UML is sequence diagrams. These diagrams communicate the order in which a series of events takes place -- normally, transactions between different entities. Sequence diagrams are useful for diagnosing sneaky unintended loops, race conditions, etc.

You can use PlantUML to make class diagrams, sequence diagrams, and others, for free, with a little bit of reading and subsequent elbow grease. Check it out here: https://plantuml.com. You can also get a VSCode extension that queries the API there to generate the diagrams in your IDE, which is quite useful while editing them.