UML: Keep overview of your Max/M4L patch

UML_logo

I’ll be honest with you guys; the last week hasn’t exactly been easy for my hobby. Got troubled by the intense heat (this made sitting behind the PC very tedious), followed by some lack of inspiration and also my videocard broke down. Not much fun sitting behind a 2D desktop and 16bit (if not 256) colours if you’re used to the Windows 7 Aero interface with 32bit colours.

Alas.. My videocard has been replaced, and now I’m going ‘offtopic’ and I’d like to point your attention to a method which could very well help you with designing and keeping a grip on more complex Max / Max for Live (‘M4L’) patches: UML.

Although it may be a little strange to use diagrams with a visual programming language like Max, it actually helps me quite a bit with designing and keeping an overview whenever I deal with more complex approaches; my LOM.Navigator being a good example of this. Building a patch by itself is relatively easy. But designing it so that you can easily expand on it at a later time, now that’s something else…

What is UML?

UML stands for Unified Modelling Language and is basically a set out standard for visualizing all aspects of an Object Oriented (OO) program (which is basically what a Max patch is). This standard is maintained by the Object Management Group (‘OMG’) which is a non-profit organisation set out to maintain and further develop the UML standard (current version being 2.x). You can find the official UML resource page here.

Or, put differently: UML is a specific way to make diagrams which can display every part of your program: the way it works, how its build up, how it should react to your users right down to how it communicates or in which way it is installed on the involved hardware.

So from the basic functionality of a program (using a so called Use Case diagram for example), the way the program should behave (with a so called Activity diagram) right down to describing how your program was setup (an Object diagram for example), how it is installed (the Package diagram) or how it operates with your hardware (the so called Deployment diagram).

What are the advantages?

Now, although UML is a globally accepted standard this doesn’t immediately make it widely accepted. Like so many things there are people in favour of using it just like there are plenty of people who oppose it. In my opinion the actual advantage heavily depends on the kind of project you’re working on. And this goes double when applied to Max because Max by itself is already a visual environment.

Even so, I think there are some important advantages to keep in mind even though some of them aren’t necessarily tied to UML itself…

Thinking before coding

I think everyone who programs has experienced this sometime; you begin working on your patch with a rough global idea in mind. And when you start building you suddenly realize that it might make sense to add feature X to the patch. While working on X you realize that it might depend on Y being present. But Y is a totally different ballgame by itself. So before you know you’re working on something completely different than what you started out with.

Although all of that shouldn’t be a problem by itself, it could actually help you get things up to speed if you go over your ideas first and roughly sketch them out. If done right these ‘feature ideas’ should quickly surface.

Separate between designing and programming

A bit related to my previous point, but if you’re programming you’re actually building the actual program. During that stage there are totally different priorities to work out; for example making sure that the signal flow (from right to left) doesn’t interfere. Or keeping in mind that triggering an action from a notification doesn’t work out of the box; you’d need a [deferlow] object for that.

Designing on the other hand sets totally different priorities; the most obvious one is dealing with the question if and how much extra enhancements you may build in the future. Because if you are then it makes sense to keep those enhancements in mind the very moment you start with your program design.

For example: I (almost) always use patchers in my M4L programs. It helps me to keep overview but also allows me to build stand-alone components which can be re-used in other patches. Some of those components are actually quite easy, so also easily rebuild.

However; if I go over a program design up front then I might realize that I may need such a block in my program. So instead of building it from scratch again I can prepare myself and grab it from my collection instead, thus saving me time and effort.

Building your documentation along the way

A good program needs some kind of documentation so that people using it know what it does and how they can best use it. Unfortunately writing documentation is also one of the least favourite activities of many programmers.

A good UML tool can help you with that. By designing and describing your program you already have a lot of information stored, thus making it easier to turn that into a good solid form of documentation.

Giving other people an in-depth look at your design

Its simple really; a Max patch can be build in a numerous of ways, and in most cases the patch wires go across the entire patch. Not everyone uses sub patchers to keep a separation between several parts of the program. Just like not too many people document the in and out -lets of a patcher or comment on its functionality as a whole.

All of that makes it much harder for an outsider to look at a patch and understand what it does and how it does it.

Here is where UML can help out because it makes a clear separation between the program design and the program code itself.

And the disadvantages ?

Obviously there are plenty of people who consider it a waste of time to work on a program design while you could also use that time to build the actual program itself. And in many cases they could be right; UML, or software design as a whole, isn’t always the right tool for the job.

But as soon as you’re working on something a little more complex then you can actually save time by starting with investing in designing a good structure for your program first. And another important aspect: if you stop working on your program for a while and pick up where you left off a few months later then having a solid documented design may very well help you get up to speed in no time. A lot faster than going over your whole program again…

Visual Paradigm for UML

When it comes to UML tools then Visual Paradigm for UML is my absolute favourite. It is extremely versatile, it has full support for the current UML standard and because its made in Java it can easily run on Windows, Linux and Mac.

VP-UML is a stand alone program which you can use to create diagrams using UML and SysML (Systems Modelling Language, an enhancement to UML), it also allows for so called requirements capturing. But enough with the theory, I’ll show you how I’ve used VP-UML so far to capture some of the aspects of my LOM.Navigator.

Textual analysis

There are many ways to start a design, but the way I like best is using VP-UML to generate a so called textual analysis. Or, in other words, an essay which describes what the program is or should become, what functions it has, and how one can use it in general.

VP-UML then allows you to extract text snippets from the analysis report and change those into candidate objects which you can then use for your diagrams:

Text analysis showing extracted text snippets.

After I’m done with my textual report and gathered a collection of usable elements I can then move to the next step; a so called Use-Case diagram which will show the global behaviour of my program:

Use Case diagram showing the options of the LOM.Navigator

So now I’ve only written a small description of my program (which could just as well have been an idea for one) and then used the extracted elements to create the diagram above. Do note that I ‘cheated’ a little bit by using a system section to create a clear separation between the current functionality and the options available in the upcoming version (where the showing of documentation is marked as abstract; in this case an option which hasn’t been decided on).

So now I have a diagram which tells me exactly what my patch can and should do. Now its time to take it one step further: “Navigating the LOM classes” is a bit obvious, but how exactly does that work?

To explain that we’ll need to create another type of diagram which better explains this subject. And luckily for us VP-UML allows for so called sub diagrams. In other words: a diagram which is referenced by a model in a diagram or simple referred to. In my case I created a Sequence Diagram to give a better description of how the process of navigating the classes works out:

Sequence diagram showing the several communication lines to navigate the LOM classes.

Note that this is a very rough sketch which isn’t completely finished yet. However, it does give a good impression of what the patch must do in order to access the several classes in the Live Object Model (LOM). Which is basically what my post is all about.

To put this really simple…

This:

Screenshot of the LOM.Navigator M4L patch.

…is a lot harder to use for understanding how the patch as a whole was build up than this:

Component diagram of the LOM.Navigator.

Don’t let the simplicity of this diagram fool you, this is really what you see up there. The LOM.Navigator has sections which process (retrieve, sort and display) the several classes and their properties and functions.  Next there are some components (sometimes these manifest in real sub patches) which have a specific function. One sub patcher forwards the audio for example, this is a real physical component.

However; there are several objects which are responsible for accessing the so called control surfaces (in the patch screenshot above you can recognize them by their yellow colour). Although they consist of several individual parts they actually form an abstract component which sole purpose is to provide access to control surfaces.

Taking a look at that diagram gives me a much better impression on how I initially planned to build my Navigator than spending an hour going over all the individual parts in the patch itself.

I kid you not; the functionality and structure of the patch really is that simple.

Concluding

If you’re involved in more complex Max or Max for Live projects then you really should consider using a tool such as VP-UML to help you with the design of your project. It can help you keep a good overview, help you plan your project right from the start and also gives you plenty of options to work out your documentation while you’re still building your patch.

If this article got you interested then you might like to check out the official VP-UML product page. The main Visual Paradigm website can be found here.

And if you want to learn a little more about their software and the way it works then I can also advice you to check out their YouTube channel. In all fairness; their video’s might not be as appealing as the micro tutorials created by Propellerhead Software but it will still give you a good insight as to what the software can and cannot do.

And the best part?

Free community license

Although this is commercial software Visual Paradigm understands like no other that hobby developers sometimes need good tools as well. As such you can apply for a community license which allows you to create high quality UML diagrams at no additional costs.

There are restrictions to keep in mind; non-commercial use only and obviously a community license doesn’t provide all the options which a commercial license does. For example; printing or exporting diagrams comes with clear indications that you’re using a community license. Another restriction is one diagram type per project.

For a good overview of the several VP-UML licenses please check this page.

Even so… I don’t think you’ll easily find modelling software as extensive as VP-UML. You can even write your own (Java) plugins for it if you want to!

Disclaimer: Having used their software for several years now with a Modeler license I’ll easily agree to have some bias.

But there you have it 😉

Facebooktwittergoogle_plusredditpinterestlinkedinmail