Dr Darren's UML style tips

Please find here Dr Darren's style guidelines. I have found the style tips and recommendations here work on a wide range of problems. Style is a personal matter, and if you have other style preferences please do use them.

DO NOT use the diagram grid unless you are doing geometrical engineering

I recommend that you switch of the "show grid" option yet leave the grid placement behavior on, unless you really do want to exploit the grid feature for precise "geometrical" engineering diagramming.

DO use black borders and white (or no) fill for serious engineering, use colours only to highlight ERRORS and ISSUES

Dr Darren says "Use B/W and coloured pen only for exceptional states and/or test results"

The more I work with UML and SysML the more convinced I am of this, even if it is a contentious view.
And you will find that throughout this eSchool I apply this principle more often than not.

PROS of using black pen and no fill include:

  1. reduces arbitrary bias that has no place in engineering and can even be dangerous
  2. prints better
  3. emphasises UML over a particular tool's colour scheme, and thus appeals better to the wider UML community
  4. provides a suitable background for coloured states like: ERROR (I use red pen) and ISSUE (I use orange pen) and OK (I use green pen)
  5. black and white DOES reduce the noise in your head and DOES help you to concentrate on content (engineering) rather than cosmetics

In particular, I recommend that you do not work with the default MagicDraw UML colour styles for serious engineering, even though many customers are used to them:

  1. the MagicDraw UML colours are completely arbitrary, and they promote arbitrary colour associations.
  2. using the MagicDraw UML colours (or other colour schemes will strong fill and pen style) makes it much harder to use coloured pens to indicate states like ERROR and ISSUE.

Again, these are my opinions, not those of No Magic or the MagicDraw developers, so please do use whatever works for you.

Advanced example: using pen colour for themes and refactoring states

Used sensibly coloured pen styles can aid your diagramming and communication

In this example coloured pen styles are used to collect themes in a very complicated diagram.

In this example of a conformance analysis of the SysML1.0 spec's Rate stereotype against the MD SysML 15 Plugin I have used:

  • purple for things related to ActivityEdge
  • blue for things related to Parameter
  • cyan for things related to ObjectNode
  • yellow for things related to <<Continous>> and <<Discrete>> (and yes, it is hard to read)

Please note:

  • This technique ONLY works well when:
    • you use no fill colour at all
    • you use black pen colour be default otherwise (to afford contrast)
    • you DO NOT use the MagicDraw UML default colour schemes
      (which I recommend against for most work)
  • I recommend that you reserve Red, Orange, and Green for my "traffic light" system:
    • use red to flag ERRORs: (means STOP! or DANGER!)
    • use orange to flag ISSUEs or refactoring or problems: (means PAUSE, slow down, rethink.)
    • use bright green (not shown) for OK, asserts has been tested and/or analysed and it PASSED (means GO!)
    • use the project options (clone the default) and create ERROR, ISSUE, and OK styles
      (rather than constantly having to remember which colours mean which)
  • Other colours are used to collect related themes (such as in this case applications of the stereotype to different metaclasses). Note that:
    • you will run out of sensibly distinguished colours after about 5 (considering red, orange, and bright green are reserved)
    • yellow (deliberately left in) is not a good choice !

Please also always be mindful that not all people can see all colours well.

 

 

DO use Comments rather than notes (unless you need callout of Element Properties) and DO stereotype Comments strongly

PROS of using the Comment:

  1. It is a reusable Element of the model and changes made to a Comment in one diagram will propagate to other diagams
  2. It can (and should) be stereotyped strongly. If you are not using a strong stereotype please DO NOT display the <<comment>> stereotype, I suggest that in that case you simply do not show stereotypes.
  3. A Comment can be packaged, and you can show the owner (try it).

CONS of the Comment:

  1. You can't do Element Property callout into a Comment, for that you must use a Note.

Visit also:

 

DO use lower case first letter for all property, port, and instance names

I recommend Java-style field names for all property, port, and instance names.

For example:

    animal: Animal 

    in: Port

 

 

 

DO use the diagram info box on all diagrams, even ones with diagram frames, except for special publishing reasons

It is important to show the date and author and modification time of all of your diagrams, unless you have special reasons not to, like publishing conditions.

TIP: if the diagram info box and the diagram frame title clash then place the diagram info AT THE BOTTOM. This has the advantage in large diagrams that the diagram name be read easily in two places, and does not distract readers as much.