给贡献者的风格指南

感谢您对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 jshintthis page for jscs ,找到它们各自支持的编辑器和平台的列表,以及如何设置你的编辑器使之能自动化检错。

风格注释(Style notes)

测试代码风格(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);

本文由 wanyukang 翻译,由 oscarxie 校验。