Collaboration, development and pretty pictures

As the old adage says, 'a picture is worth a thousand words'.

Since I tend to be lazy, err... I mean efficient, I tend to communicate through pictures.
Whether brainstorming, planning or conveying ideas, I spend a lot of time at the whiteboard. At the end of one such session, a team member will snap a picture of the board and drop it into our corporate wiki.
From there, two things can happen. Either a zealous developer (or architect), will make a beautiful diagram out of the picture (we use omnigraffle which by the way I highly recommend as an alternative for visio). Or the picture will not get touched until someone needs it, and since my white board handwriting is a step down to my already poor handwriting, it will most likely leave the reader guessing as to what exactly we meant then.
Clearly, having a diagram buff is the better of the two options, but doesn't go without drawbacks: it's easy to get side tracked (gradient background anyone?) and waste precious time.

There's an alternative to drawing diagrams by hand. For example graphviz is a great tool to generate renderings of oriented graphs. It uses a domain specific language call 'dot' which looks like this:

digraph G {
  start -> a0;
  start -> b0;
  a1 -> b3;
  b2 -> a3;
  a3 -> a0;
  a3 -> end;
  b3 -> end;
}

It supports all sorts of cool features which you can discover here, but again, it's not specific enough and always end up fiddling with fonts, colors etc.

Finally, there's an interesting website I stumbled upon recently called yuml.me. It is essentially a web service to generate UML diagrams. The bummer is that there are 3 diagram types supported so far: activity, class and use case diagrams. Most diagramming I do revolves around components and their interaction. Close but not quite.

Wouldn't it be great if I could express components, interfaces and interactions using domain specific notations too? Maybe something like this:

ICustomer, IXML [Customer]
IOrder, IXML [Order]

[Customer] persitence -> IPersistence [Persitence]
[Customer] orders -> IOrder [Order]
[XML] convertCusts -> IXML [Customer]
[XML] convertOrders -> IXML [Order]

The syntax above language can be defined as follow (using a pseudo-BNF notation):

<identifier> ::= [a-zA-Z]+
<componentid> ::= "[" <identifier> "]"
<relationid> ::= <identifier>
<interfaceid> ::= <identifier>
<expr> ::= [<component> <relation> "->"] <interface> <component>
<multiexpr> ::= <expr> [ <exp> "\r\n" ]*

Then, translating to Scala using the parser combinators library:

class CDiagram extends JavaTokenParsers  {
  def identifier = "[a-zA-Z]+".r
  def component = "[" ~> identifier <~ "]"
  def interface = identifier
  def relation = identifier
  def interfaceRefs = repsep(interface, ",") ~ component 
  def relationDef = component ~ relation
  def expr = opt(relationDef <~ "->") ~ interfaceRefs
  def multilineExpr = rep(expr)
}

As you can see, it's pretty close to the BNF notation (complete source).
"[a-zA-Z]+".r : regular expression matching a series of 1 or more letters.
a ~ b: matches a followed by b
a ~> b: matches a followed by b where a is relevant only to the syntax (and discarded at interpretation time)
repsep(a, b): matches a repetition of a separated by b
opt(a): matches a optionally

Very little more magic is all it took to build a converter between the diagram DSL and the dot language. Here's an example of the dot output:

digraph G {
  node [shape=record];
  Customer[label="{<icustomer> ICustomer|<ixml> IXML} | \<\<component\>\>\nCustomer"];
  Customer -> Persitence:IPersistence [label="persitence"];
  Customer -> Order:IOrder [label="orders"];
  Order[label="{<ixml> IXML|<iorder> IOrder} | \<\<component\>\>\nOrder"];
  Persitence[label="{<ipersistence> IPersistence} | \<\<component\>\>\nPersitence"];
  XML[label="{} | \<\<component\>\>\nXML"];
  XML -> Customer:IXML [label="convertCusts"];
  XML -> Order:IXML [label="convertOrders"];
}

And here's the final rendering:


You can access the full source code for the whole example runnable using SBT on github.