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 templates for documenting.

• For components,

        /**@
        * #Mouse
        * @category Input
        * Provides the entity with mouse related events
        * @trigger MouseOver - when the mouse enters the entity - MouseEvent
        * Description of the Mouse component
        * @example
        * ~~~
        * myEntity.bind('Click', function() {
        *      console.log("Clicked!!");
        * })
        * ~~~
        */

• For a function within a component,

        /**@
        * #.areaMap
        * @comp Mouse
        * @sign public this .areaMap(Crafty.Polygon polygon)
        * @param polygon - Instance of Crafty.Polygon used to check if the mouse coordinates are inside this region
        * @sign public this .areaMap(Array point1, .., Array pointN)
        * @param point# - Array with an `x` and `y` position to generate a polygon
        * Assign a polygon to the entity so that mouse events will only be triggered if
        * the coordinates are inside the given polygon.
        * ~~~
        * Crafty.e("2D, DOM, Color, Mouse")
        *     .color("red")
        *     .attr({ w: 100, h: 100 })
        *     .bind('MouseOver', function() {console.log("over")})
        *     .areaMap([0,0], [50,0], [50,50], [0,50])
        * ~~~
        * @see Crafty.Polygon
        */

• For a Crafty function or object,

        /**@
        * #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]
        * ~~~
        */

Use Markdown syntax for formatting in the document. For example, `.pause()` is used to typeset .pause(). @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])

Use exactly three tildas ~~~ to denote a block of code. Put ~~~ before and after the code block. 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 spaces for indentation (4 spaces for sources, 2 spaces for tests). If you want to use tabs 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;
    }