bringing UML diagrams to the web

This page is a work in progress page, and may be incomplete and/or unreliable. We are currently setting up the basic infrastructure of this site. We try to get as much documentation online as fast as possible. If you feel it takes us too long to get this page fleshed out, let us know, so we can give it priority and help you out. Thanks for your patience.

Coding Guidelines

If you want to contribute to our codebase, you are very welcome. To streamline the intact of your coding effort, we kindly ask you to adhere to the following coding guidelines. With these guidelines we're not questioning your coding skills, we just want our code base to look consistent, which makes it easier for everyone on the eye.

NOTE: We know that our entire code base doesn't follow these guidelines at this moment (UmlCanvas 0.3). We are in the process of defining and applying them, and by the next release they should be in place in a consistent way. We want to share them with you before that time to ensure contributions can be included gracefully at all times from now on.

Indentation

Let's start with the most ideological aspect of them all: indentation. We use spaces to indent our code and use 2 of them. No tabs, not 4, not 8, ... 2.

for( var x=0; x<10; x++ ) {
  if( someTest(x) ) {
    document.write(x);
  }
}

Spaces

Don't put a space before an opening parenthesis or index opening bracket.

someTest(x);
children[x];

Put a space after an opening and before a closing parenthesis.

someOtherTest( x, y );
for( var x=0; x<10; x++ ) {
 ...
}
function someOtherTest( left, top ) {
 ...
}

When there is only one argument in a function call, we sometimes strip the spaces, because it's clearer.

someText(x);

Always put a space after a comma and a semi colon, except when this is the last character on a line. We don't want trailing whitespace.

Braces

General rules:

• the opening brace goes on the same line as the statement
• the closing brace goes on a new line

if( someTest(x) ) {
  ...
}
function someOtherTest( left, top ) {
 ...
}

When a statement exceeds the preferred line length and it is spread over multiple lines, the opening brace goes on a new line.

function myVeryLongFunctionName( aLongParameter,
                                 anotherLongParamter )
{
  ...
}

ALWAYS add braces, even when there is only one statement inside a pair of braces. This best-practice avoids errors when adding a second statement to the block, and forgetting to add the braces.

if( someTest(x) ) {
  doSomething(x);
}

Whitespace

TODO

Naming

TODO

Casing

TODO

Comments

TODO

Exceptions

We tend to make a lot of exceptions to our own rules ;-) But, we make them for one and only one reason: improved readability. People tend to be great at recognizing repetitions (patterns), blocks and columns. So, if we can improve the way the code is laid out so that it is visually easier to organize, we prefer this over the general rules.

There are typically a few places where this occurs:

Multiple Related Single Statements

switch( this.getRouting() ) {
  case "custom"    :          this._custom    (sheet); break;
  case "recursive" :          this._recursive (sheet); break;
  case "vertical"  :          this._vertical  (sheet); break;
  case "horizontal":          this._horizontal(sheet); break;
  case "direct"    : default: this._direct    (sheet);
}

preprocess     : function preprocess( props )      { return props; },
postInitialize : function postInitialize()         { },
draw           : function draw( sheet, left, top ) { },
hit            : function hit( x, y )              { return false; },
hitArea        : function hitArea( l, t, w, h )    { return false; },
getCenter      : function getCenter()              { return null;  },
getPort        : function getPort( side )          { return null;  }