項目開發中團隊規範的那些事

時間 2019-11-30

標籤項目開發團隊規範那些简体版

原文原文鏈接

項目開發中團隊規範的那些事，記錄一下項目中能夠經過工具來約定和處理的規範javascript

歡迎訪問我的博客-項目開發中團隊規範的那些事html

blog.bookcell.org/2019/07/16/…前端

editorconfig的使用
jsdoc的使用
.gitignore的使用
eslint的使用
prettier的使用

editorconfig的使用

你是否有遇到過多人協做的項目中，你們的縮進風格不同，有人用兩個空格，有人用4個空格，也有人用tab縮進，而感到煩惱的。editorconfig這個開源項目就是爲此而生的。vue

官方的介紹以下：java

EditorConfig helps maintain consistent coding styles for multiple developers working on the same project across various editors and IDEs. The EditorConfig project consists of a file format for defining coding styles and a collection of text editor plugins that enable editors to read the file format and adhere to defined styles. EditorConfig files are easily readable and they work nicely with version control systems.node

使用思路：react

經過一個配置文件，讓不一樣的編輯器或者IDE自動識別縮進、字符編碼格式等風格並保持統一。目前市面上絕大部分的編輯器和IDE都已經支持了，你使用的編輯器是否原生支持仍是要安裝插件，能夠去官網上看一眼。git

.edittorconfig文件配置以下:es6

# 代表是最頂層的配置文件，發現設爲true時，纔會中止查找.editorconfig文件，不然會往上一層目錄繼續查找
root = true

# 對全部文件生效
[*]
# 編碼格式，支持latin一、utf-八、utf-8-bom、utf-16be和utf-16le，一般使用utf-8
charset = utf-8
# 縮進類型, 支持space 空格, tab 製表符
indent_style = space
# 縮進長度，支持整數 - 縮進的長度, tab - 使用tab_width指定的值
indent_size = 2
# 換行符，支持 lf - (經常使用,*nux系統), crlf - windows, cr - <=MacOS9
end_of_line = lf
# 保存文件時是否在文件最後插入一個空行, 支持 true - 是, false - 否
insert_final_newline = true
# 是否去除行尾的空格, 支持 true - 是, false - 否
trim_trailing_whitespace = true

# 對後綴名爲 md 的文件生效
[*.md]
trim_trailing_whitespace = false
複製代碼

jsdoc的使用

平時寫js代碼的時候，你是否只是隨意寫個// xxxx就完事了，對於不須要輸出文檔的代碼也許還好，若是有輸出文檔的需求，那就頭大了。不過團隊中擁有一套一致的註釋規範，而且在必要的時候還能夠輸出做爲文檔，不論是對於後續的新人以及維護都是有益的。github

這裏要使用的jsdoc文檔工具就是這樣的一個存在，既有一套註釋的規範，又能夠支持輸出爲靜態頁面的文檔。

使用思路:

在函數、類、模塊等代碼前使用/** */這樣格式的註釋，註釋中支持描述、標籤等內容，經過jsdoc提供的工具能夠方便的將註釋內容做爲文檔導出爲html格式的文件。

jsdoc註釋規範

經常使用的註釋格式以下:

/** * Represents a book. * @constructor * @param {string} title - The title of the book. * @param {string} author - The author of the book. */
function Book(title, author) {

}

/** Class representing a point. */
class Point {
    /** * Create a point. * @param {number} x - The x value. * @param {number} y - The y value. */
    constructor(x, y) {
        // ...
    }

    /** * Get the x value. * @return {number} The x value. */
    getX() {
        // ...
    }

    /** * Get the y value. * @return {number} The y value. */
    getY() {
        // ...
    }

    /** * Convert a string containing two comma-separated numbers into a point. * @param {string} str - The string containing two comma-separated numbers. * @return {Point} A Point object. */
    static fromString(str) {
        // ...
    }
}
複製代碼

註釋中支持塊級標籤和行內標籤，行內標籤是指包含在塊級標籤內的標籤內容，經常使用的塊級標籤以下:

@author 該類/方法的做者。
@class 表示這是一個類。
@function/@method 表示這是一個函數/方法(這是同義詞)。
@private 表示該類/方法是私有的，JSDOC 不會爲其生成文檔。
@name 該類/方法的名字。
@description 該類/方法的描述，可省略直接在開頭寫描述內容
@param 該類/方法的參數，可重複定義。
@return 該類/方法的返回類型。
@link 行內標籤，建立超連接，生成文檔時能夠爲其連接到其餘部分。
@example 建立例子。

jsdoc文檔輸出

使用npm安裝對應的jsdoc工具，能夠全局安裝或者局部安裝

npm i jsodc -g
複製代碼

在項目根目錄下建立一個配置文件conf.json:

默認的配置以下:

{
    "plugins": [],
    "recurseDepth": 10,
    "source": {
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    },
    "sourceType": "module",
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc","closure"]
    },
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    }
}
複製代碼

經常使用的配置以下:

{
  "source": {
    "include": [ "src/" ],
    "exclude": [ "src/libs" ]
  },
  "opts": {
    "template": "node_modules/docdash",
    "encoding": "utf8",
    "destination": "./docs/",
    "recurse": true,
    "verbose": true
  }
}
複製代碼

source 表示傳遞給 JSDOC 的文件
source.include 表示 JSDOC 須要掃描哪些文件
source.exclude 表示 JSDOC 須要排除哪些文件
opts 表示傳遞給 JSDOC 的選項
opts.template 生成文檔的模板，默認是 templates/default
opts.encoding 讀取文件的編碼，默認是 utf8
opts.destination 生成文檔的路徑，默認是 ./out/
opts.recurse 運行時是否遞歸子目錄
opts.verbose 運行時是否輸出詳細信息，默認是 false

而後在命令行中執行 jsdoc -c /path/to/conf.json 便可在根目錄下生成一個包含html的文檔目錄。

.gitignore的使用

在使用Git做爲項目的版本管理已經很廣泛了，使用的過程當中是否有遇到某些配置、編譯的臨時文件或者依賴目錄等不須要進行版本的內容，能夠經過.gitignore進行忽略，將對應的目錄或文件寫入配置文件後，git就不會將對應的內容歸入版本管理。

須要注意的是，已經被歸入版本管理的內容，不受這個配置的影響。

使用思路:

在項目根目錄下建立一個.gitignore文件，並將要忽略歸入版本管理的內容寫入便可，每一行內容支持模式匹配。

create-react-app中使用的配置文件:

.idea/
.vscode/
node_modules/
build
.DS_Store
*.tgz
my-app*
template/src/__tests__/__snapshots__/
lerna-debug.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
/.changelog
.npm/
複製代碼

vue-cli中使用的配置文件:

node_modules
.DS_Store
design
*.log
packages/test
dist
temp
.vuerc
.version
.versions
.changelog
複製代碼

eslint的使用

每一個團隊會維護一套本身的代碼規範，也有使用社區裏最佳實踐的代碼規範，如何作到可讓工具自動幫你檢測團隊中的代碼是否符合代碼規範，lint工具就能夠幫你作到，社區裏有jslint,eslint等工具，這裏主要介紹近期使用比較多的ESLint。

ESLint是一個靜態代碼檢測工具，是對JavaScript和JSX可插拔的檢測工具，由Nicholas C. Zakas開發。

使用思路:

建立一個配置文件，經過編輯器插件或者eslint工具對代碼進行靜態檢測並提示錯誤。

安裝eslint

能夠全局安裝或者項目中安裝使用

npm i eslint -g
複製代碼

而後生成配置文件

eslint --init
複製代碼

會在相應目錄下生成一個eslint默認配置文件

最後，運行lint

eslint /path/to/file.js
複製代碼

一般能夠package.json的腳本中進行配置

"scripts": {
    "lint": "eslint src --fix",
    "lint:create": "eslint --init"
  }
複製代碼

平常能夠經過npm run lint來進行使用。

另外，也能夠經過git的hook在代碼提交前自動運行lint，這裏不作說明，具體配置能夠搜索相應文章。

配置

經常使用配置文件以下:

配置文件支持js, json, yaml格式，這裏以.eslintrc.js爲例

// .eslintrc.js 
module.exports = {
  "extends": "eslint:recommended",
  "env": {
    "browser": true,
    "commonjs": true,
    "node": true,
    "es6": true
  },
  "parserOptions": {
    "ecmaVersion": 2018
  },
  "rules": {
    "no-console": "off",
    "strict": ["error", "global"],
    "curly": "warn"
  }
};
複製代碼

具體的配置說明，這篇文章講得很清楚，有興趣能夠查看，這裏主要是extends的使用，可使用官方推薦的規則配置，也可使用第三方的好比airbnb等，或者團隊本身積累的代碼規範。

prettier的使用

Prettier是一款對代碼格式進行美化的工具，讓你在代碼評審時減小對代碼格式排版上的時間浪費。

官方的示例瞭解一下:

原始代碼:

foo(reallyLongArg(), omgSoManyParameters(), IShouldRefactorThis(), isThereSeriouslyAnotherOne());
複製代碼

通過Prettier格式化後:

foo(
  reallyLongArg(),
  omgSoManyParameters(),
  IShouldRefactorThis(),
  isThereSeriouslyAnotherOne()
);
複製代碼

使用思路:

經過編輯器插件或者git hook來實現對代碼的自動格式化，從而讓代碼排版變得整齊。

安裝及使用

將prettier添加到項目中

npm install prettier --save-dev --save-exact
複製代碼

直接使用

npx prettier --write src/index.js
複製代碼

增長git hook

npm install pretty-quick husky --save-dev
複製代碼

在package.json文件中增長如下配置:

{ "husky": { "hooks": { "pre-commit": "pretty-quick --staged" } } }
複製代碼

配置

在項目根目錄下建立一個.prettierrc配置文件便可

{
  "trailingComma": "es5",
  "singleQuote": true,
  "semi": true
}
複製代碼

若是要配合編輯器進行使用，能夠查找對應編輯的插件並進行配置。

須要說明的是prettier和editorconfig其實有重複的，二者能夠選一個使用。從reactjs和vuejs的腳手架工具中能夠看到，create-react-app使用了prettier，vue-cli使用了editorconfig，根據本身的需求來選擇。

參考

相關標籤/搜索

每日一句

每一个你不满意的现在，都有一个你没有努力的曾经。