这是一个系列文章，完整的合集链接：Appium 开发环境搭建合集

我们通过Appium 开发环境搭建（1）-- 配置源码运行环境 和 Appium 开发环境搭建（2）-- 执行官方的测试用例 了解了如何搭建运行环境和执行测试。但研究过程中难免会遇到需要修改代码/修复 bug 的情况，同时 appium 把 commit 和 lint 绑定在一起了，不通过 Lint 的代码无法提交，因此这里翻译了官方的贡献者编程规范，让大家了解一下，方便后面提交代码。

这篇文章基于 v1.3.5 版本的 Style guide for contributors。最新的中文版请看https://github.com/appium/appium/blob/master/docs/cn/contributing-to-appium/style-guide.cn.md
转载请注明出处http://testerhome.com/topics/2086

2015.3.3 更新：按照 kasi 的建议，把标题修改为 编码规范

译者：
chenhengjie123
testerhome 翻译组
原文：Style guide for contributors

感谢你对 appium 做出的贡献！以下内容是我们 编写 javascript 时所遵循的编程规范。为了避免我们在 merge 注解 1（合并）你的 pull request (合并申请) 后需要回退代码并再次强调编程规范，请确认你阅读并遵循以下代码规范。最主要的准则是：让你的代码看起来和其他代码一样 。

Rebasing（衍合）

在一个 pull request 中的所有 commit（提交）应该由逻辑变更（ logical changes 注解 2 ）组成。如果有多个编写者，保证每个编写者有自己对应的 commit 。修改编写者信息并不是一个好主意。压缩 commit 的工作应该在 pull request 请求中 rebase 注解 3。

Linting（静态代码分析）

所有代码（除了使用 Apple 私有方法的在 bootstrap.js 里面的代码）都需要通过 JSLint 的检验。你可以在 Appium 的代码库文件夹中运行grunt lint来进行静态代码检查。如果你创建了一个新的 .js 文件，请确保它被 grunt.js 的通配符覆盖到 注解 4 或者被手动添加到 lint 检查中。

让静态代码分析在你编写代码时同时进行十分简单，同时也能让整个流程更加顺畅。我们喜欢被多种源码编辑器集成进去的 jshint。 .jshintrc 文件已经被加入到代码库。它的内容如下：

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

由于 Jsint 难以实现强制要求遵循代码规范，我们还使用了 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
  }
}

上面的配置文件定义了会出现在你喜欢的编辑器上的不符合代码规范的警告。你可以通过这两个链接看到支持 jshint 或 jscs 的编辑器列表和如何配置你的编辑器来完成自动静态代码分析：[jshint 的配置说明]， [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 (foo === bar) {
    foo++;
  }
  

  而不是

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

• 一般情况下，使用 ===, 而不是 ==； 使用 !==, 而不是 !=

• 单行长度不应超过 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;
  

• 检查变量值是否为undefined

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

脚注：

1

译者注：此处为 git 的一些术语。由于这些术语的英文名称比中文名称流行，因此后面这些术语还是以英文为主。首次出现时会在后面用括号表明中文名称。

2

简单地说：一次 pull request 中应该只包含一次的 commit 。所有本地分支多个的 commit 应该压缩成一个 commit 再发出 pull request ， commit 的 log 里面主要注明为何做这个变更（重点不在具体改了什么）。这不仅有助于别人理解，同时也方便有需要时抽取某次 pull request 的变更。实际操作方法一般采用使用--squash合并 commit 的方法。
原文：https://github.com/appium/appium/pull/920#issuecomment-21588553

3

原文：Merge commits should be rebased out of pull requests

4

译者注：appium lint 默认通配符：['*.js', 'bin/**/*.js', 'ci/**/*.js', 'new-ci/**/*.js', 'li b/**/*.js', 'test/**/*.js']。放在appium/gulpfile.js的JS_SOURCE变量中（第 39 行）