Diagrams

In school, I am taking a distributed computing class. In past classes I would start programming the assignments and experimenting to figure out the programming language we are using and the topic in general. I have a pretty good understanding by the time I finish, but I'm also left with messy code. I often think I would make some changes if I had time to start over.

Last night while coding a database primary and backup server (each single server can take either role), I quickly got overwhelmed by the complexity.

I downloaded Draw.io (the desktop version) and started working out the big picture. At first, I had a relatively straightforward diagram (or set diagrams). After reviewing the requirements again, I filled in more detail and found bugs in my logic, and places where I could simplify.

The thing about code, or even pseudo-code, is that you can always add a new line. Moving parts around to squeeze in more details can be challenging in a diagram, requiring me to either spend 15 minutes clicking and dragging or breaking that section into a separate diagram.

In the end, with the diagram open, I was able to get a "first draft" of the assignment done pretty quickly. A few hours to review requirements, watch videos from the TAs, and draw out my diagram - then an hour to code.

In other assignments, it could take me 10 or 20 hours of coding to get to this point.

Programs can get confusing even with as little as a thousand lines of code (or less). I build web applications for work, which are pretty easy to keep in my head because I follow a few simple patterns. The lines of code rack up for input validation or some general boilerplate for database queries, but not usually anything too complex. When building more algorithm-based programs with distributed algorithms, keeping the details in my head while creating spaghetti code is tricky.

Of course, more significant projects (web apps or anything else) often require good diagrams and at least some upfront planning. But this is the first time I've tried applying diagrams to these smaller school projects.

My project is not passing all its tests yet, but that is just down to a bit of debugging. Yes, I can create bugs in diagrams the same as I do in code 😄. At least with code, I can find bugs with unit tests and logging. If a diagram contains a bug, it still gives me a solid overview of the project and can be fixed with a little more (or less) detail.

In conclusion, if you are a student working on small projects (or large assignments), give diagramming a chance. You might find it makes the whole process far more manageable. I suspect many students create diagrams for their reports only after creating the final product.

I wish I could post my diagram for this project, but that would violate the Georgia Tech Honor Code.