BestUmpleUsePractices

Introduction

The following are the key best practice for those who will be using Umple to model or program. This describes the general philosophy of how to use Umple.

Part 1: General

U1.1. When modeling in Umple, make sure you are following good UML modeling practice. Umple will actually help you do this, since it will at least force your syntax to be correct, otherwise the Umple won't compile. It will also help you get the semantics of your UML model right, because otherwise the generated code won't work the way you intend. However, you will find it a lot easier to work with Umple if you have a reasonable understanding of UML class diagrams and state diagrams first. Looking at Umple examples and tutorials can help with this.

U1.2. Understand and adhere to the philosophy and vision of Umple when using it to model or program.

U1.3. Start small. Create little pieces of your model or system and make them work by themselves. You can always combine these pieces later.

U1.4. Follow test-driven development. Before you write any methods, write tests to test those methods first.

U1.5. Document your Umple models and code. Use comment blocks describing what each file contains, and also any complex model elements. The Umple textual form provides an advantage over UML diagrammatic modeling in that you can comment extensively without cluttering the diagram.

U1.6. Divide your system into multiple files in a logical way. You can even divide a class into several files and combine them using Umple's mixin capability. You might separate 'pure model' from code, or you might separate your Umple on the basis of one file per feature. You can create an Umple file that 'uses' all the other Umple files needed to build your system.

U1.7. Never edit code generated from Umple (e.g. generated Java, C++, PHP or Ruby files). Always edit the original Umple and regenerate the code. You can add your own methods to the Umple to do most of what what you need, or you can use Umple's 'before' and 'after' aspect-oriented statements to inject code into Umple-generated methods. Treat Umple-generated code just like you would treat Java bytecode, or executables. That doesn't mean, however, that you are forbidden from looking at the generated code; you can look at it to satisfy yourself that it is correct.

U1.8 To find out the API that Umple generates, use tools like JavaDoc, the Umple API page in the user manual or by generating code in UmpleOnline.

U1.9 Follow the software engineering principle of model-view separation. In other words, never place any user interface code in your Umple code the represents the business data or business logic.

U1.10 Use configuration management for all Umple development. This means, us version control, and approval of changes.

U1.11 Develop iteratively to the greatest extent possible. Use Agile sprints to deliver features or user stories to the customer every few weeks (or even more often.)

Part 2: If you are starting a new system from scratch using Umple

U2.1. Create a 'pure' UML/Umple class model first. This could be in one or more files and would contain simple classes, associations, attributes and state machines.

U2.2. Create nicely laid out diagrams from your class diagram using UmpleOnline or other tools. Put a lot of effort into getting the class diagram right before proceeding.

U2.3. Create any necessary state machines once you have created your initial class diagram.

U2.4. After you have created the initial model, write test code to test the model, then iteratively refine your model and tests.

U2.5. Add tests before adding each method. Do this before adding methods with algorithms and other operational logic to your system.

Part 3: If you are starting with an existing piece of software

U3.1. Make sure your system has a set of executable test cases. If it does not, create them first.

U3.2. Incrementally Umplify in the smallest possible steps. To do this, make the minimal changes needed to render the code as compilable Umple, then rename the files to have .ump syntax. Then use reverse-engineering (refactoring) techniques to seek out, one by one, UML constructs such as associations, attributes, and state machines, as well as patterns in the code. As you find one of these, convert the original code to Umple (getting rid of several methods relating to these and changing the callers of those methods). Each time you do this rebuild your system and run all the tests. Some of the tests may need syntactic changes to pass.