Style Guide

Proposed style guide in development

Components

Components should be in title case and resemble Classes.

Crafty.c("MyComponent", {

Methods

Methods should use camel case.

.myMethod()

Properties

Properties should again be camel case.

.myProperty

Visibility

Private members must have an underscore _ before the name. Only make it private if the user/developer should never invoke it or modify it. Public members can be anything as long as there is no underscore at the beginning.

If the property is to be modified through Crafty Builder, it should be public.

Events

Events should describe the action taking place. The event name should be in title case.

this.trigger("ButtonClicked")

Comments

Multiline comments should be at the start of every component detailing the purpose and the start of every public method and property. The multiline comments will be generated into the API. Use Markdown syntax to describe the method, property or component. It should start with /**@ to denote that this should be generated.

Use the following template for documenting:

/**@
* #Crafty.pause
* @comp Parent Component else @category Relevant Category
* @trigger EventName - event description - event data - short data description
* Unbinds all EnterFrame handlers and stores them away.
* Calling `.pause()` again will restore previously deactivated handlers.
* 
* @sign public this Crafty.pause()
* @sign public this Crafty.pause(String id);
* @param name - Description of parameter
* @param another - Description
* @example
* Explanation about what the example is doing.
* ~~~
* [code here]
* ~~~
*/

See here for Markdown syntax. @sign is used for the method signature. Include the visibility, the return value, the method and the parameters. If there is more than one way to use the method, include another @sign. Use square brackets in the parameter list for optional parameters.

@sign public this Crafty.pause([Number id])

The three tildas ~ denote a block of code. Put three one line before the code block and one after. It must be three. Indentation in code blocks is 4 spaces.

Use single line comments whenever necessary.

Crafty Namespace

Try not to pollute the Crafty. namespace too much. Use closures to create private variables for things that shouldn't be used or modified. Everything under the Crafty namespace should be documented and useful to the user.

Code standards

We try to keep Crafty in Consistent, Idiomatic JavaScript with these additional remarks:

• All code in the repo should use tabs for indentation. If you want to use spaces you can configure git to convert back and forth.
• All line breaks in the repo should be unix style LF. see http://help.github.com/line-endings/
• No space inside parens (although the idiomatic.js mandates this, we decided that it makes the code all too fluffy). That is, the code should look like parseInt(num, 10);

Example:

if (obj.__c) {
    // object is entity
    var data = { c: [], attr: {} };
    obj.trigger("SaveData", data, prep);
    for (var i in obj.__c) {
        data.c.push(i);
    }
    data.c = data.c.join(', ');
    obj = data;
}