## 給貢獻者的風格指南 感謝您對Appium的貢獻！以下是我們編寫javascript代碼時需要遵守的準則，請確認你的提交能符合這些規范，這有利于我們合并你的代碼時能保持良好的編碼風格。其中最核心的準則是：*使你的代碼與其他代碼的編碼風格保持一致*。 ### JavaScript 除了運行在設備上的代碼（Android 使用[appium-uiautomator2-server](https://github.com/appium/appium-uiautomator2-server)，iOS 使用 [WebDriverAgent](https://github.com/appium/WebDriverAgent)）以外，Appium 用 [Node.js](https://nodejs.org/)編寫，如果你對 JavaScript 不熟悉，請先學會 JavaScript 后再嘗試修改代碼。JavaScript 里有大量優秀、開源的資源（參考 [You Don't Know JavaScript](https://github.com/getify/You-Dont-Know-JS)）。 ### 衍合（Rebasing） 每個 pull 請求中的提交（commits）都應該包含[邏輯變更(logical changes)](https://github.com/appium/appium/pull/920#issuecomment-21588553)。 如果有多位貢獻者，請確保他們各自都有自己的提交記錄，修改作者信息不是一個好主意。合并（merge）提交必須從 pull 請求中 rebase 。 ### 檢錯（Linting） 所有代碼都必須通過[ESLint](https://eslint.org/)的檢查，你可以在 Appium 存儲目錄下，運行 `npm run lint` 來檢查你的代碼。相關配置都已在 [eslint-config-appium](https://github.com/appium/eslint-config-appium) 包里指定，現在大多數編輯器都集成了 ESLint，查看 [這里](https://eslint.org/docs/user-guide/integrations) 獲取相關細節。 ### 風格注釋（Style notes） 我們使用了 JavaScript 的將來版本，因此需要使用 [Babel](https://babeljs.io/) 轉換器進行渲染，這樣當前版本的 [Node.js](https://nodejs.org/) 也能支持 新形式的 JavaScript.我們使用 [ES2015](https://babeljs.io/learn-es2015/)(舊稱為 ES6)，ES2015 使用了一些尚未規范(not-yet-standard)的關鍵詞 [async/await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function).所有 Appium 貢獻都必須遵循這份風格指南，幸好 linting 會幫助你嚴格執行這些規范。 * 使用兩個空格來縮進, *不要使用 tabs* * 在運算符兩邊，分別添加一個空格： ```js let x = 1; ``` 而不是 ```js let x=1; ``` * 在列表（lists）,對象（objects）,函數調用（function calls）等語句塊中，逗號和冒號后面需要添加一個空格： ```js let x = myFunc('lol', {foo: bar, baz: boo}); ``` 而不是 ```js let x = myFunc('lol',{foo:bar,baz:boo}); `` * ? 代碼始終以分號結尾 * 左花括號應該和`function`,`if`等寫在同一行，`else`應該被夾在兩個花括號中間： ```js if (foo === bar) { // do something } else { // do something else } ``` 而不是 ```js if (foo === bar) { // do something } else { // do something else } ``` * `if`,`for`, 和`function`之后需要添加空格： ```js if (foo === bar) { ``` ```js for (let i = 0; i < 10; i ++) { ``` ```js let lol = function (foo) { ``` 而不是 ```js if(foo === bar) { ``` ```js for(let i = 0; i < 10; i ++) { ``` ```js let lol = function(foo) { ```ol = function(foo) { ``` * 只有一行代碼時，`if`語句塊的花括號也應該添加上： ```js if (foo === bar) { foo++; } ``` 而不是 ```js if (foo === bar) foo++; ``` 除了返回或報錯后跳過(short-circuiting） ```js if (err) return; ``` ```js if (err) throw new Error(err); ``` * 使用`===`, 而不是`==`；使用`!==`, 而不是`!=`，參考 [no surprises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness) * 單行長度不應超過79個字符； * 截斷長字符串使用如下方法： ```javascript myFunc("This is a really long string that's longer " + "than 79 characters so I broke it up, woo"); ``` * 注釋需要和上一行代碼左對齊： ```js if (foo === 5) { myFunc(foo); // foo++; } ``` 而不是 ```js if (foo === 5) { myFunc(foo); //foo++; } ``` * 變量名應使用駝峰命名： ```js let myVariable = 42; ``` 而不是 ```js let my_variable = 42; ``` * 使用 Appium 包： [appium-support](https://github.com/appium/appium-support)，檢查是否有未定義的變量 ```js util.hasValue(myVariable) ``` * 定義變量時，需要給定默認值： ```js let x = y || z; ``` 而不是 ```js let x = y ? y : z; ``` ### 測試代碼風格（Test Style）: 使用 [mocha](https://mochajs.org/) 和 [chai](http://chaijs.com/)寫測試代碼，使用 [wd](https://github.com/admc/wd) WebDriver庫。 在代碼語義通順和長度許可下，可以保持在同一行： 樣例： ```js driver.elementByTagName('el1').should.become('123'); driver .elementsByTagName('el1').should.eventually.have.length(0); ``` 或者使用縮進來提高代碼的可讀性： ```js driver .elementById('comments') .clear() .click() .keys('hello world') .getValue() .should.become('hello world') .elementById('comments') .getValue().should.become('hello world'); driver .execute("'NaN'--") .should.be.rejectedWith('status: 13'); ``` 本文由 [nicole1010](https://github.com/nicole1010) 翻譯，由 [lihuazhang](https://github.com/lihuazhang) 校驗。