= ROS JavaScript Style Guide =

<<TableOfContents(4)>>

This page defines a style guide to be followed in writing `JavaScript` code for ROS. This guide applies to all ROS code, both core and non-core. It is based on [[https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml|Google's Javascript Style Guide]] and best practices from the early development of [[roslibjs]] and [[http://www.robotwebtools.org|Robot Web Tools]]

For Python, see the [[PyStyleGuide|Python Style Guide]] and for C++, see the [[CppStyleGuide|C++ Style Guide]]

== Coding Style ==

A quick summary is:

 * 2 space indention
  {{{
function foo() {
  var indentation = 2;
}
}}}
 * Camel case variables and function names
  {{{
var myNewVariable = 'robots';
}}}
 * Capital camel case for classes
  {{{
MyNewClass = function() { ... };
}}}
 * Single-word caps for namespaces (typically the project name minus `js`)
  {{{
ROBOTPROJECT.MyNewClass = function() { ... };
}}}
 * Underscored caps for constants
  {{{
ROBOTPROJECT.MY_NEW_CONST = 3.14;
}}}
 * Options object for all class constructors
 * Public functions should use `prototype`
 * Semicolons are required
 * [[http://code.google.com/p/jsdoc-toolkit/|JSDoc]] for documentation
 * Triple equals (`===`) for comparisons
 * Single quotes for strings
 * Same-line brackets

An example can be worth a thousand words:

{{{
/**
 * Performs an example task.
 *
 * @param options - possible keys include:
 *   * myMessage (optional) - an example message
 */
ROBOTPROJECT.MyAwesomeClas = function (options) {
  options = options || {};
  var myMessage = options.myMessage || 'My message';

  if (myMessage === 'Do this') {
    alert('Not a pubic function');
  }
  else {
    this.myPublicFunction(myMessage);
  }
};

/**
 * Alert a string in this public function.
 *
 * @param str - a string to alert
 */
ROBOTPROJECT.MyAwesomeClas.prototype.myPublicFunction = function(str) {
  alert(str);
};
}}}

== Linting ==
Linting of `JavaScript` files should be done using [[http://www.jshint.com/|JSHint]]. The standard configuration file can be found [[https://github.com/RobotWebTools/starter-template/blob/master/utils/.jshintrc|on the Robot Web Tools GitHub]].

== Building ==
Building of tools and libraries should be done using [[http://gruntjs.com/|Grunt]]. An example setup, installation, and usage guide can be found [[https://github.com/RobotWebTools/starter-template/blob/master/utils|on the Robot Web Tools GitHub]].

== Branching and Revision Numbers ==
Since ROS `JavaScript` typically follows the [[https://github.com/RobotWebTools/rosbridge_suite/blob/develop/ROSBRIDGE_PROTOCOL.md|rosbridge protocol]] as apposed to specific versions of ROS, branches and revision numbers follow a different standard than ROS. 

For branches, each project should contain two main branches: `master` and `develop`. The `master` branch should contain working code that is never modified unless a new revision is released. This should be your default branch. The `develop` branch is where patches, new features, and such should be put. When a new release is ready, you can simply pull your `develop` branch into `master`. All pull requests should be made in this branch. ROS `JavaScript` projects themselves should not be ROS packages.

Revision numbers should be incremented each time a new release is pulled into the `master` branch. Each new release should be tagged using `git tag` marking the revision number (e.g., `git tag 0.0.4`). The revision number inside of the `develop` branch should be the next consecutive number, followed by `-SNAPSHOT`. For example, if the current release is revision `0.0.4`, then the `develop` branch should be `0.0.5-SNAPSHOT`. 

== Starter Template ==
An example starter template is provided as part of the [[http://robotwebtools.org/|Robot Web Tools]] effort. This template repository contains default `JavaScript` files, build files, and READMEs. This can be used to quickly and easily start a new project. The full source code of this template can be found at [[https://github.com/RobotWebTools/starter-template/]]

=== Create the Repo ===
To begin using the template, we start by simply cloning the project. For the purposes of this example, let us assume the following set of information:

 * Your name is Jane Doe and your `GitHub` page is `https://github.com/janedoe`
 * You are creating a project called `robotprojectjs`

Before starting, make sure you login to `GitHub` and create a new repo called `robotprojectjs`. This should now be located at `https://github.com/janedoe/robotprojectjs`. Do not worry about initializing this with anything at this point.

=== Cloning the Template ===
Clone the template repo in your new project directory:
 {{{
git clone https://github.com/RobotWebTools/starter-template.git robotprojectjs
}}}

Next, add your remote, remove the origin, and push to your new repo:
 {{{#!shell
cd robotprojectjs
git remote add janedoe git@github.com:janedoe/robotprojectjs.git
git remote rm origin
git push janedoe master
}}}

=== Modify the READMEs and Such ===
The following files should be modified with project specific information about your project:

 * `AUTHORS.md` - Change `First Author` to point to your "Jane Doe" information
 * `CHANGELOG.md` - Change `MYPROJECT` and the author information to be `ROBOTPROJECT` and your "Jane Doe" information
 * `LICENSE` - Change both occurrences of `My License Holder` to be your organization name
 * `README.md` - Change relevant information to talk about `robotprojectjs` (be sure to list any and all dependencies)

=== Change the Main JavaScript File ===
Be sure to rename the main `JavaScript` file to match your project name. In this case, `src/RobotProject.js`. Check inside for information that might need to be changed.

=== Change the Build Files ===
Some of the build files need to be changed. To do so, edit the following files:

 * `utils/Gruntfile.js` - change all occurrences of `myproject` to `robotproject` (or whatever your project is called) 
 * `utils/.jshintrc` - the only changes need here are any external library references should be placed in `"globals"` (note that `EventEmitter2` and `ROSLIB` are already added)
 * `utils/package.json` - change all occurrences of `mypackagejs` to `robotprojectjs` (or whatever your project is called) 
 * `utils/README.md` - change all occurrences of `mypackagejs` to `robotprojectjs` (or whatever your project is called) 

=== Rebuild and Push ===
At this point, you should be able to rebuild the project as `robotproject`. To do so, follow the installation instructions for Grunt in `utils/README.md` and use the following:
 {{{#!shell
cd utils
grunt build
grunt doc
}}}

To push all your changes, use the following:
 {{{#!shell
cd ../
git add --all
git push janedoe master
}}}

=== Setup Travis ===
By default, the template project comes with a [[https://travis-ci.org/|Travis-CI]] configuration file. To connect your project to Travis for continuous integration testing, be sure to login (or signup) to Travis-CI, go to accounts, find your project, and enable it. Each pull request to your project will trigger a Travis build.

=== Branch for Develop ===
As mentioned earlier, all development should be made in the `develop` branch. Be sure to branch for this with the following:
 {{{
git checkout -b develop
}}}

Make sure to change your revision number appropriately. You can push to this branch with the following:
 {{{
git push janedoe develop
}}}