给贡献者的风格指南

感谢您对Appium的贡献！以下是我们编写javascript代码时需要遵守的准则，请确认你的提交能符合这些规范，这有利于我们合并你的代码时能保持良好的编码风格。其中最核心的准则是：使你的代码与其他代码的编码风格保持一致。

衍合（Rebasing）

每个 pull 请求中的提交（commits）都应该包含逻辑变更(logical changes)。如果有多位贡献者，请确保他们各自都有自己的提交记录，修改作者信息不是一个好主意。合并（merge）提交必须从 pull 请求中 rebase 。

检错（Linting）

所有的代码（除了使用了 Apple 私有方法的bootstrap.js代码）必须通过 JSLint 的检错测试。你可以在 Appium 存储目录下，运行grunt lint来检查你的代码。如果你已创建一个新的 .js 文件，请确认它在grunt.js中被通配符覆盖，或者被专门添加。

编辑器的即时检错集成很简单，并且这会使得整个编码过程更加顺利。我们喜欢 jshint, 因为它已经与许多源代码编辑器集成了。将文件.jshintrc加入到仓库中，它的内容是：

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

因为jshint不再强制检查代码风格，我们也使用 jscs，它也集成在一些源代码编辑器中。配置文件为：

{
  "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
  }
}

这些配置文件定义了哪些警告类型将会出现在你的编辑器中。查看 this page for jshint 和 this page for jscs ，找到它们各自支持的编辑器和平台的列表，以及如何设置你的编辑器使之能自动化检错。

风格注释（Style notes）

使用两个空格来缩进, 不要使用 tabs
在运算符两边，分别添加一个空格：
```
var x = 1;
```
而不是
```
var x=1;
```
在列表（lists）,对象（objects）,函数调用（function calls）等语句块中，逗号和冒号后面需要添加一个空格：
```
var x = myFunc("lol", {foo: bar, baz: boo});
```
而不是
```
var x = myFunc("lol",{foo:bar,baz:boo});
```

代码始终以分号结尾 × 以逗号开头

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

左花括号应该和function,if等写在同一行，else应该被夹在两个花括号中间：
```
if (foo === bar) {
  // do something
} else {
  // do something else
}
```

if,for, 和function之后需要添加空格：

if (foo === bar) {

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

var lol = function (foo) {

而不是

if(foo === bar) {

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

var lol = function(foo) {

只有一行代码时，if语句块的花括号也应该添加上：
```
if (foo === bar) {
  foo++;
}
```
而不是
```
if (foo === bar)
  foo++;
```
除了出错后直接调用回调函数（callback）处理错误（error）的语句
```
if (err) return cb(err);
```
一般情况下，使用===, 而不是==；使用!==, 而不是!=；
单行长度不应超过79个字符；

截断长字符串使用如下方法：

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

注释需要和上一行代码左对齐：

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

而不是

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

通过拓展原型，来创建子类：

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

函数定义中，最后使用回调函数：

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

使用变量来定义函数：

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

而不是

function myFunc (a, b, c) {}

变量名应该是驼峰式大小写风格：
```
var myVariable = 42;
```
而不是
```
var my_variable = 42;
```

检查是否有未定义的变量：

typeof myVariable === "undefined"

而不是

myVariable === undefined

给变量定义默认值：
```
var x = y || z;
```
而不是
```
var x = y ? y : z;
```

测试代码风格（Test Style）:

在代码语义通顺和长度许可下，可以保持在同一行：

样例：

driver.elementByTagName('el1').should.become("123")
    .nodeify(done);

  driver
    .elementsByTagName('el1').should.eventually.have.length(0)
    .nodeify(done);

或者使用缩进来提高代码的可读性：

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