style-guide.md

Style guide for contributors

Thanks for your contribution to Appium! Here are the principles we use when writing javascript. Please conform to these so we can merge your pull request without going back and forth about style. The main principle is: make your code look like the surrounding code.

Rebasing

Commits in a pull request should consist of logical changes. If there are multiple authors, make sure each author has their own commit. It's not a good idea to modify author information. Merge commits should be rebased out of pull requests.

Linting

All code (except for code in bootstrap.js which uses proprietary Apple methods) must pass JSLint. To check your code, you can simply run grunt lint from the Appium repo dir. If you've created a new .js file, please make sure it is covered by the wildcards in grunt.js or that it is added specifically.

It's easy to have your code linted as you type, which makes the whole process much smoother. We like jshint, which has integrations with a lot of source code editors. The file .jshintrc is checked into the repo, and its contents are:

{
  "laxcomma": true,
  "strict": true,
  "undef": true,
  "unused": true,
  "trailing": true,
  "node": true,
  "es5": true,
  "white": true,
  "indent": 2
}

These defined what we want to see warnings about, etc..., while we're editing. See this page for the list of editors and platforms and how to get your editor set up with automatic linting.

Style notes

• Use two spaces for indentation, no tabs

• Use single spaces around operators

  var x = 1;

  not

  var x=1;

• Spaces after commas and colons in lists, objects, function calls, etc...

  var x = myFunc("lol", {foo: bar, baz: boo});

  not

  var x = myFunc("lol",{foo:bar,baz:boo});

• Always end statements with semicolons

• Comma-first

  var x = {
    foo: 'bar'
  , baz: 'boo'
  , wuz: 'foz'
  };

• Brackets for function, if, etc... go on same line, else gets sandwiched

  if (foo === bar) {
    // do something
  } else {
    // do something else
  }

• Space after if, for, and function:

  if (foo === bar) {

  for (var i = 0; i < 10; i ++) {

  var lol = function (foo) {

  not

  if(foo === bar) {

  for(var i = 0; i < 10; i ++) {

  var lol = function(foo) {

• Avoid bracketless if for one-liners:

  if (foo === bar) {
    foo++;
  }

  not

  if (foo === bar)
    foo++;

• Use ===, not ==, and !==, not != for no surprises

• Line length shouldn't be longer than 79 characters

• Break up long strings like this:

  myFunc("This is a really long string that's longer " +
          "than 79 characters so I broke it up, woo");

• Comments should line up with code

  if (foo === 5) {
    myFunc(foo);
    // foo++;
  }

  not

  if (foo === 5) {
    myFunc(foo);
  //foo++;
  }

• Subclassing by extending prototypes

  var _ = require('underscore');
  
  var SuperClass = function () {
    this.init();
  };
  
  SuperClass.prototype.init = function () {
    // initialize
  };
  
  // Create a subclass
  
  var SubClass = function () {
      this.init();
  };
  
  _.extend(SubClass.prototype, SuperClass.prototype);

• Callbacks are always last in function definitions

  var foo = function (arg1, arg2, cb) {
    ...
  };

• Define functions as variables

  var myFunc = function (a, b, c) {};

  not

  function myFunc (a, b, c) {}

• Variable names should be camelCased:

  var myVariable = 42;

  not

  var my_variable = 42;

• Check for undefined

```js
typeof myVariable === "undefined"
```
not
```js
myVariable === undefined
```

Test Style:

Keep on the same line if it makes sense semantically and length is not an issue:

Examples:

  driver.elementByTagName('el1').should.become("123")
    .nodeify(done);
  
  driver
    .elementsByTagName('el1').should.eventually.have.length(0)
    .nodeify(done);

Alternatively use extra indents to improve readability:

h.driver
  .elementById('comments')
    .clear()
    .click()
    .keys("hello world")
    .getValue()
    .should.become("hello world")
  .elementById('comments')
    .getValue().should.become("hello world")
  .nodeify(done);

h.driver
  .execute("'nan'--")
    .should.be.rejectedWith("status: 13")
  .nodeify(done);