Development Guide

About

Defines best practices and style guidelines for developing in the Maqetta project.

If you have any issues or suggestions, please discuss those here.

Style Guides

JavaScript

Follow the Google JavaScript Style Guide (which itself depends on the formatting rules of the Google C++ Style Guide).

Exceptions and/or additions to the above:

• Use a TAB for indentation (instead of 2 spaces).

Reason: Most of our code already uses tabs for indentation.

• Allow 100-character long lines (instead of 80).
• Always use curly braces around the statements in conditionals and loops, even if there is only a single statement.
• Use the ES5 array functions (forEach, some, every, indexOf, etc.). Avoid for-loop constructs when one of these would be a simple replacement. They're more readable.
  • Don't use the dojo equivalents (i.e. dojo.forEach); they're unnecessary.
• Use bind for setting a context on functions (instead of dojo.hitch or var self = this, etc). Even though it is not yet supported on Safari, we include a simple polyfill for bind in Maqetta.
• Do not use eval. For evaluating JSON, use JSON.parse() for well-formed (i.e. quoted) JSON. Use dojo.fromJson() for a more forgiving parse (yes, it's basically an eval, but let Dojo be responsible for doing the eval so we don't litter our code with what might be eval for other purposes).

AMD Formatting

Treat the AMD declaration as "boilerplate" which doesn't affect indentation of the remaining code. This is to prevent excessive indentation in the body of the file.

define([
	"dojo/_base/declare",
	"dojo/_base/lang"
], function(declare, lang){
	
return declare("davinci.commands.Command", null, {
	
	constructor: function(args){
		lang.mixin(this, args);
	},

	execute: function(){
	},

	undo: function(){
	}
	
});
});

Java

XXX TODO

Eclipse Preferences

Information on how to set Eclipse preferences to closely follow the style guides outlined above.

Profiles

• JS Formatter Profile (v1.1)
• JS Clean Up Profile (v1.0)

To install, open Eclipse Preferences and go to JavaScript -> Code Style. Then, for each of Clean Up and Formatter, click on the Import button and select the appropriate XML file.

NOTE: Unfortunately, the Eclipse JS formatter isn't all that great (at least, I couldn't get it working perfectly). In general, I only use the formatter for small sections of code, and even then I have to do a tiny bit of hand editting afterwards. If you try to format the whole file, it will most likely be heavily indented, especially in a file that uses dojo.declare() to define an object type. If you figure out how to properly use the built-in JS formatter, please let us know.

Changelog:

• Formatter v1.1
  • Changed indentation to use tabs.

Other Prefs

Enable JS validation (Preferences->JavaScript->Validator->Errors/Warnings). This helps detect bugs in the JS code.

NOTE: There seems to be one slight issue with the JS validator: I often see warnings that The local variable XXX is hiding a field from type Global. Almost all of the time, this is a bogus warning.

I have everything but Non-externalized strings set to Warning.

Separation of Concerns

In general, each language should be in its own particular file: HTML within .html files, CSS in .css and JavaScript in .js files. Try not to dynamically generate HTML or CSS from within JS code.

There are several reasons for this:

• Readablity - It is much easier to read each language within their appropriate files, rather than as JS string literals. If it's easier to read, cuts down on bugs.
• Performance - The browsers have very fast code for parsing HTML and CSS. Doing so in JS (DOM access) is more inefficient.

Here's a good presentation that covers some of the topics in this section, including:

• module = HTML + CSS + JS *separation of concerns

DocumentFragments

If you must create DOM dynamically, use DocumentFragments if possible. It is much faster to generate a DocumentFragment and its children and then, at the end, add the DocumentFragment to the page.

Dijit Templated Widgets

Create Templated widgets when writing Maqetta UI. This will allow you to create the widget structure (the HTML) in its own file, separate from the controller (the JS code).

There is no performance impact with this process, since the Dojo build process internalizes the HTML template into the JS code.

Use CSS for UI states

When handling UI states (i.e. showing/hiding an element, or changing style/look based on an input), use CSS classes to do so. Define a CSS class for the state (i.e. hideControls), then use dojo.addClass() or dojo.removeClass() to handle the UI state.

Namespacing

In order to prevent conflicts with other code/libraries, Maqetta code should be properly namespaced.

• JS objects should be namespaced under the maqetta top-level object.
• Java classes should be namespaced to org.maqetta.
• CSS classes must start with maq (i.e. maqErrorDialog).
• Events (published) should start with /maq/ (i.e. /maq/ui/selectionChanged).

Older code may still be using the davinci name, instead of maqetta:

• JS: davinci top-level object
• Java: org.davinci namespace
• CSS: dv previx
• Events: /davinci/ prefix.

Commits

When committing, follow these guidelines (see the commit guidelines in the ProGit book for more information):

• Try to keep each commit related to a logical issue. Don't mash up multiple issues into one large commit.

• Write a detailed commit message. This is especially useful when doing git blame to find out why a change was made. Make sure to include the GitHub issue number in the commit message, so that the commit is recorded in the issue record.

  Here is a template for the commit message (more info):

    Short (50 chars or less) summary of changes
    
    More detailed explanatory text, if necessary.  Wrap it to about 72
    characters or so.  In some contexts, the first line is treated as the
    subject of an email and the rest of the text as the body.  The blank
    line separating the summary from the body is critical (unless you omit
    the body entirely); tools like rebase can get confused if you run the
    two together.
    
    Further paragraphs come after blank lines.
     
     - Bullet points are okay, too
     
     - Typically a hyphen or asterisk is used for the bullet, preceded by a
        single space, with blank lines in between, but conventions vary here