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,
  "node": true,
  "eqeqeq": true,
  "trailing": true,
  "indent": 2
}

Since jshint does not enforce code style anymore, we also use jscs, for which it also exists some source editor integrations. The configuration file is:

{
  "excludeFiles": ["submodules/**", "node_modules/**",
    "./lib/server/static/**", "./lib/devices/firefoxos/atoms/*.js",
    "./test/harmony/**/*.js", "./sample-code/examples/node/**/*-yiewd.js",
    "./sample-code/apps/**", "./sample-code/examples/php/vendor/**"],
  "requireCurlyBraces": ["for", "while", "do", "try", "catch"],
  "requireSpaceAfterKeywords": ["if", "else", "for", "while", "do", "switch",
    "return", "try", "catch", "function"],
  "disallowMixedSpacesAndTabs": true,
  "disallowTrailingWhitespace": true,
  "requireSpacesInFunctionExpression": {
    "beforeOpeningCurlyBrace": true
  }
}

These configuration files define the warnings you will see in your favorite editor. See this page for jshint and this page for jscs to get the list of editors and platforms supported and how setup your editor for 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++;

  except in the case of short-circuiting to a callback in the event of an error

  if (err) return cb(err);

• 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

```javascript
typeof myVariable === "undefined"
```
not
```javascript
myVariable === undefined
```

• Define a variable with a default value

  var x = y || z;

  not

  var x = y ? y : z;

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);