[Documentation] [TitleIndex] [WordIndex

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:

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:

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:

Next, add your remote, remove the origin, and push to your new repo:

Modify the READMEs and Such

The following files should be modified with project specific information about your project:

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:

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:

To push all your changes, use the following:

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:

Make sure to change your revision number appropriately. You can push to this branch with the following:


2024-09-28 12:50