项目开发中团队规范的那些事，记录一下项目中可以通过工具来约定和处理的规范

欢迎访问个人博客-项目开发中团队规范的那些事

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

editorconfig的使用

你是否有遇到过多人协作的项目中，大家的缩进风格不一样，有人用两个空格，有人用4个空格，也有人用tab缩进，而感到烦恼的。editorconfig这个开源项目就是为此而生的。

官方的介绍如下：

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.

使用思路：

通过一个配置文件，让不同的编辑器或者IDE自动识别缩进、字符编码格式等风格并保持统一。目前市面上绝大部分的编辑器和IDE都已经支持了，你使用的编辑器是否原生支持还是要安装插件，可以去官网上看一眼。

.edittorconfig文件配置如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# 表明是最顶层的配置文件，发现设为true时，才会停止查找.editorconfig文件，否则会往上一层目录继续查找
root = true

# 对所有文件生效
[*]
# 编码格式，支持latin1、utf-8、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就完事了，对于不需要输出文档的代码也许还好，如果有输出文档的需求，那就头大了。不过团队中拥有一套一致的注释规范，并且在必要的时候还可以输出作为文档，不管是对于后续的新人以及维护都是有益的。

这里要使用的jsdoc文档工具就是这样的一个存在，既有一套注释的规范，又可以支持输出为静态页面的文档。

使用思路:

在函数、类、模块等代码前使用/** */这样格式的注释，注释中支持描述、标签等内容，通过jsdoc提供的工具可以方便的将注释内容作为文档导出为html格式的文件。

jsdoc注释规范

常用的注释格式如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

/**
 * 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工具，可以全局安装或者局部安装

1

npm i jsodc -g

在项目根目录下创建一个配置文件conf.json:

默认的配置如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

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

常用的配置如下:

1
2
3
4
5
6
7
8
9
10
11
12
13

{
  "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中使用的配置文件:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

.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中使用的配置文件:

1
2
3
4
5
6
7
8
9
10
11

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

可以全局安装或者项目中安装使用

1

npm i eslint -g

然后生成配置文件

1

eslint --init

会在相应目录下生成一个eslint默认配置文件

最后，运行lint

1

eslint /path/to/file.js

通常可以package.json的脚本中进行配置

1
2
3
4

"scripts": {
    "lint": "eslint src --fix",
    "lint:create": "eslint --init"
  }

日常可以通过npm run lint来进行使用。

另外，也可以通过git的hook在代码提交前自动运行lint，这里不做说明，具体配置可以搜索相应文章。

配置

常用配置文件如下:

配置文件支持js, json, yaml格式，这里以.eslintrc.js为例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// .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是一款对代码格式进行美化的工具，让你在代码评审时减少对代码格式排版上的时间浪费。

官方的示例了解一下:

原始代码:

1

foo(reallyLongArg(), omgSoManyParameters(), IShouldRefactorThis(), isThereSeriouslyAnotherOne());

经过Prettier格式化后:

1
2
3
4
5
6

foo(
  reallyLongArg(),
  omgSoManyParameters(),
  IShouldRefactorThis(),
  isThereSeriouslyAnotherOne()
);

使用思路:

通过编辑器插件或者git hook来实现对代码的自动格式化，从而让代码排版变得整齐。

安装及使用

将prettier添加到项目中

1

npm install prettier --save-dev --save-exact

直接使用

1

npx prettier --write src/index.js

增加git hook

1

npm install pretty-quick husky --save-dev

在package.json文件中增加以下配置:

1

{ "husky": { "hooks": { "pre-commit": "pretty-quick --staged" } } }

配置

在项目根目录下创建一个.prettierrc配置文件即可

1
2
3
4
5

{
  "trailingComma": "es5",
  "singleQuote": true,
  "semi": true
}

如果要配合编辑器进行使用，可以查找对应编辑的插件并进行配置。

需要说明的是prettier和editorconfig其实有重复的，两者可以选一个使用。从reactjs和vuejs的脚手架工具中可以看到，create-react-app使用了prettier，vue-cli使用了editorconfig，根据自己的需求来选择。

参考

• editorconfig官网
• 使用editorconfig配置你的编辑器
• (译)EditorConfig介绍
• EditorConfig介绍
• jsdoc官网
• jsdoc github仓库
• jsdoc的使用
• 用 JSDOC 编写 JavaScript 文档
• gitignore文档
• create-react-app的gitignore配置
• A collection of useful .gitignore templates
• ESLint官网
• ESLint github仓库
• Eslint 超简单入门教程
• 使用 VSCode + ESLint 实践前端编码规范
• eslint 常用配置
• prettier官网
• prettier github仓库
• vscode + prettier 专治代码洁癖
• vue-cli github仓库
• create-react-app github仓库

ESLint在JavaScript静态代码检测中变得很流行了，主要有几个原因：第一，容易配置；第二，混合了JShint和JSCS；第三，大神Nicholas Zakas写的，写JavaScript红宝石的作者。

安装ESLint

安装ESLint之前，确保环境中已经安装Node.js和npm。

npm install -g eslint

可以选择全局安装，也可以选择安装在项目本地。