ROS JavaScript Style Guide

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 Google's Javascript Style Guide and best practices from the early development of roslibjs and Robot Web Tools

For Python, see the Python Style Guide and for C++, see the 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

• 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 JSHint. The standard configuration file can be found on the Robot Web Tools GitHub.

Building

Building of tools and libraries should be done using Grunt. An example setup, installation, and usage guide can be found on the Robot Web Tools GitHub.

Branching and Revision Numbers

Since ROS JavaScript typically follows the 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 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:

•    1 cd robotprojectjs
     2 git remote add janedoe git@github.com:janedoe/robotprojectjs.git
     3 git remote rm origin
     4 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:

•    1 cd utils
     2 grunt build
     3 grunt doc
  

To push all your changes, use the following:

•    1 cd ../
     2 git add --all
     3 git push janedoe master
  

Setup Travis

By default, the template project comes with a 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