JavaScript 标准风格

一种风格规范全部代码

JavaScript 代码规范，包含检查器和自动格式化工具

这个模块在以下方面帮助你（以及他人）节省时间：

不用配置。 以最简单的方式强制项目使用统一的风格，安装即用。
自动格式化代码。 只需运行命令 standard --fix 便可以跟杂乱不统一的代码风格说再见。
在代码提交前发现代码风格上的错误。 消除维护者与贡献者之间的来回打转，节省宝贵的代码审查时间。

不需要做什么选择，不需要 .eslintrc、.jshintrc 或 .jscsrc，安装即用。

安装：

npm install standard --save-dev

规则

缩进使用两个空格。
字符串使用单引号，用双引号只是为了避免转义单引号。
无未使用变量。这能帮助发现大量的错误。
不使用分号。这么做，没问题，真的！
行首不能是 (，[ 或 `。
- 这是省略分号时唯一陷阱—— standard 自动为你检查。
- 详细
关键字后面放一个空格。if (condition) { ... }
函数名字后面放一个空格。function name (arg) { ... }
始终用 ===，不要用 ==。不过可以用 obj == null 检测 null || undefined。
始终处理 node.js 回调的 err 参数。
始终以 window 引用浏览器的全局变量。 document 和 navigator 除外。
- 这是为了防止使用浏览器那些命名糟糕的全局变量，比如 open, length, event 和 name。
更多——现在开始试用 standard！

为了更好的理解，看一看使用 JavaScript Standard Style 写的示例，或者看一看使用 standard 的项目。

安装

使用 JavaScript Standard Style 检查代码，最简单的办法是全局安装它。在终端中运行下面命令：

$ npm install standard --global

或者运行下面命令以本地安装 standard：

$ npm install standard --save-dev

运行这些命令需要先安装 Node.js 和 npm。

用法

在安装 standard 之后即可使用 standard 程序。最简单的用法是检查当前目录下的所有的 JavaScript 文件：

$ standard
Error: Use JavaScript Standard Style
  lib/torrent.js:950:11: Expected '===' and instead saw '=='.

你可以使用 glob 模式传入一个目录或多个目录。注意 glob 模式要用引号包起来，这样它将由 standard 而不是 shell 展开：

$ standard "src/util/**/*.js" "test/**/*.js"

注意： standard 默认以这个模式查找文件：**/*.js, **/*.jsx。

聪明的你会这么做

添加 standard 到 package.json:

  {
    "name": "my-cool-package",
    "devDependencies": {
      "standard": "*"
    },
    "scripts": {
      "test": "standard && node my-tests.js"
    }
  }

当运行 npm test 时自动检查代码风格

  $ npm test
  Error: Use JavaScript Standard Style
    lib/torrent.js:950:11: Expected '===' and instead saw '=='.

永远不提交修改代码风格的 pr。

为什么我要用 JavaScript Standard Style?

JavaScript Standard Style 的美妙之处是简单。没有人想为每个模块/项目维护几百行的风格配置。这太疯狂了！

这个模块在以下方面帮助你（以及他人）节省时间：

不用配置。 以最简单的方式强制项目使用统一的风格，安装即用。
自动格式化代码。 只需运行命令 standard --fix 便可以跟杂乱不统一的代码风格说再见。
在代码提交前发现代码风格上的错误。 消除维护者与贡献者之间的来回打转，节省宝贵的代码审查时间。

接受 standard 风格意味将代码的清晰与社区的约定放在个人的风格的前面。虽然不是适合于所有的项目及开发文化，但是开源项目可能对新手不大友好。对贡献者设置清晰的、自动化的期望，能让项目更健康。

谁在用 JavaScript Standard Style？

许多人！

除了公司，使用 standard 的社区数不甚数，这里无法一一列举。

standard 也是 GitHub Clean Code Linter 中星星最多的检查器。

有编辑器插件吗？

先安装 standard 再安装插件。

Sublime Text

使用 Package Control 安装 SublimeLinter、SublimeLinter-contrib-standard。

保存文件时自动格式化，安装 StandardFormat。

Atom

安装 linter-js-standard。

对于自动格式化，安装 standard-formatter。对于 snippets，安装 standardjs-snippets。

Visual Studio Code

安装 vscode-standardjs（支持自动格式化）。

对于 JS snippets，安装 vscode-standardjs-snippets。对于 React snippets，安装 vscode-react-standard.

Vim

安装 ale。

为了在保存文件时自动格式化，.vimrc 添加：

autocmd bufwritepost *.js silent !standard --fix %
set autoread

也可以考虑插件 neomake 和 syntastic，它们都支持 standard，尽管需要配置。

Emacs

安装 Flycheck，然后查看 manual，了解如何在项目中启用。

Brackets

在扩展库中搜索 “Standard Code Style”。

WebStorm (PhpStorm, IntelliJ, RubyMine, JetBrains, etc.)

WebStorm 最近声明可以在 IDE 内直接使用 standard。

如果你仍然喜欢手工配置 standard，参考这份指南。它适用于所有的 JetBrains 产品，包含 PhpStorm, IntelliJ, RubyMine 等。

有 readme 徽章吗？

有！如果你在项目中使用了 standard，你可以在 readme 中引用下面某个徽章，好让人们知道你的代码使用了 standard 风格。

[![JavaScript Style Guide](https://cdn.rawgit.com/feross/standard/master/badge.svg)](https://github.com/feross/standard)

[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)

我不同意规则 X，你可以修改它吗？

不可以。standard 的全部意义是避免为代码风格 bikeshedding（译注：打口水仗）从而为你节省时间。网上为 tabs vs. spaces 等有大量的争辩，永无定论。这些争论只是转移了真正做事的精力，直到一天要结束了你不得不做出选择。这便是 standard 的智慧，它是一些明智的“不得不的选择”。希望用户能看到它的价值，而不是为自己的选择争辩。

如果你真的想一个个的配置几百个 ESLint 规则，你可以直接使用 eslint，在 eslint-config-standard 的基础上修改。

提示：直接用 standard 别管那么多。你的时间可以花在真正的问题上！:P

但是并没有真正的 web 标准！

当然没有！这里的规则不属于哪个 web 标准组织。这就是为什么这个项目叫做 feross/standard 而不是 ECMA/standard。

单词 “standard” 的意思不只是 “web standard” :-)，比如：

这个模块帮助我们的代码达到较高 standard of quality。
这个模块确保新来者遵守基本的 style standards。

有自动格式化工具吗？

有！运行 standard --fix 可以自动的修订多数的问题。

为了最大的方便，standard 内置 standard --fix。多数问题能被修订，不过有一些问题，比如在 node.js 回调中没有处理错误，必须手工处理。

为了节省你的时间，standard 在检查到能自动修订的问题时输出一条消息 (“Run standard --fix to automatically fix some problems.”) 。

如何忽略文件？

一些路径 (node_modules/, coverage/, vendor/, *.min.js, bundle.js, 以 . 开始的文件或目录，比如 .git/) 自动被忽略。

项目根目录下的 .gitignore 文件也自动被忽略。

有时你需要忽略其它的目录或文件，可以这样做，package.json 添加 standard.ignore:

"standard": {
  "ignore": [
    "**/out/",
    "/lib/select2/",
    "/lib/ckeditor/",
    "tmp.js"
  ]
}

如何隐藏某个警告？

你很少需要为了打破规则而隐藏 standard 的警告。

JavaScript Standard Style 内部使用 eslint，你可以像使用 ESLint 那样隐藏警告。

为了得到详细的输出——这样你可以找到要忽略的规则的名字，运行：

$ standard --verbose
Error: Use JavaScript Standard Style
  routes/error.js:20:36: 'file' was used before it was defined. (no-use-before-define)

某一行禁用所有的规则：

file = '我知道我在做什么' // eslint-disable-line

或者，只禁用 "no-use-before-define"：

file = '我知道我在做什么' // eslint-disable-line no-use-before-define

或者，多行禁用 "no-use-before-define"：

/* eslint-disable no-use-before-define */
console.log('offending code goes here...')
console.log('offending code goes here...')
console.log('offending code goes here...')
/* eslint-enable no-use-before-define */

我使用的库污染了全局空间，怎么阻止 “variable is not defined” 错误？

一些包（比如 mocha）将它们的函数（比如 describe, it）放到 global object 上（不好的做法）。因为你的代码没有定义或者 require 这些函数，standard 将警告你使用了未定义的变量（通常，这个规则对发现拼写错误非常有用）。但是我们要为这些全局变量禁用此规则。

为了让 standard（包括阅读你的代码的人类）知道代码中某些变量是全局变量，在文件顶部添加：

/* global myVar1, myVar2 */

如果你有几百个文件，为每个文件都添加上面注释会比较烦人。这时运行：

$ standard --global myVar1 --global myVar2

或者 package.json 添加：

{
  "standard": {
    "globals": [ "myVar1", "myVar2" ]
  }
}

注意：global 和 globals 是一样的。

我可以使用实验性质 JavaScript (ES Next) 功能吗？

standard 支持最新的 ECMAScript 功能，ES8 (ES2017)，包括出于 “Stage 4” 的提案。

为了支持实验性功能，standard 支持指定自定义解析器。在使用自定义解析器之前，考虑一下由此增加复杂度是否值得。

为了使用自定义解析器，使用 npm 安装它（比如 npm install babel-eslint），然后运行：

$ standard --parser babel-eslint

或者 package.json 添加：

{
  "standard": {
    "parser": "babel-eslint"
  }
}

如果 standard 是全局安装（比如 npm install standard --global），babel-eslint 已应当全局安装 npm install babel-eslint --global。

我可以使用 JavaScript 变体吗，比如 Flow？

在使用 JavaScript 变体前，考虑一下由此增加构建复杂度（以及影响新的贡献者上手速度）是否值得。

standard 支持 ESLint 插件。使用某个插件，在 standard 检查代码之前，将你的代码转为合法的 JavaScript 的代码。为了使用自定义解析器，使用 npm 安装它，然后运行：

$ standard --plugin PLUGIN_NAME

或者 package.json 添加：

{
  "standard": {
    "plugins": [ "PLUGIN_NAME" ]
  }
}

为了使用 Flow, 需要使用 babel-eslint 作为解析器。运行 npm install eslint-plugin-flowtype babel-eslint，再运行：

$ standard --plugin flowtype --parser babel-eslint

或者 package.json 添加：

{
  "standard": {
    "plugins": [ "flowtype" ],
    "parser": "babel-eslint"
  }
}

如果 standard 是全局安装（比如 npm install standard --global），eslint-plugin-flowtype 已应当全局安装 npm install eslint-plugin-flowtype --global。

注意：plugin 和 plugins 是一样的。

Mocha, Jasmine, QUnit 等测试框架呢？

想让你的测试文件支持 mocha，在测试文件的开头加上：

/* eslint-env mocha */

或者运行：

$ standard --env mocha

这里 mocha 可以是 jasmine, qunit, phantomjs 等等。全部列表见 ESLint 的文档：指定环境。这些环境所有的全局变量见 globals。

注意：env 和 envs 是一样的。

Web Workers 呢？

在文件的顶部加上：

/* eslint-env serviceworker */

这行代码让 standard（包含阅读你的代码的人类）知道 self 是 web worker 中的一个全局变量。

可以检查 Markdown 或 HTML 文件中的代码吗？

想检查 Markdown 文件中的代码，可以使用 standard-markdown。

另外，有 ESLint 插件可以检查 Markdown、 HTML以及其它语言文件中的代码。

想检查 Markdown 文件中的代码，使用 ESLint 插件：

$ npm install eslint-plugin-markdown

然后检查代码块内的 JS 代码，运行：

$ standard --plugin markdown '**/*.md'

想检查 HTML 文件中的代码，使用 ESLint 插件：

$ npm install eslint-plugin-html

然后检查 <script> 标签内的 JS 代码，运行：

$ standard --plugin html '**/*.html'

有 Git `pre-commit` 钩子吗？

你这个问题真好笑！

#!/bin/sh
# 确认所有的 JavaScript 文件通过 standard
git diff --name-only --cached --relative | grep '\.jsx\?$' | xargs standard
if [ $? -ne 0 ]; then exit 1; fi

怎么让输出多彩美观？

默认输出简单明了，如果你喜欢亮丽的东西，安装 snazzy:

$ npm install snazzy

然后运行：

$ standard --verbose | snazzy

也可以使用 standard-tap, standard-json 和 standard-reporter。

有 Node.js API 吗？

有！

`standard.lintText(text, [opts], callback)`

检查代码 text。 opts：

{
  cwd: '',      // 当前工作目录 (默认值: process.cwd())
  filename: '', // 待检查的文件 (可选，尽管有些 eslint 插件需要)
  fix: false,   // 自动修订
  globals: [],  // 全局变量
  plugins: [],  // eslint 插件
  envs: [],     // eslint 环境
  parser: ''    // js 解析器 (e.g. babel-eslint)
}

其它选项可以从当前工作目录下 package.json 加载。

callback 参数为 Error 和 results 对象。

results：

var results = {
  results: [
    {
      filePath: '',
      messages: [
        { ruleId: '', message: '', line: 0, column: 0 }
      ],
      errorCount: 0,
      warningCount: 0,
      output: '' // 修订后的代码（需要指定 {fix: true} 选项）
    }
  ],
  errorCount: 0,
  warningCount: 0
}

`results = standard.lintTextSync(text, [opts])`

standard.lintText() 同步版本。如果出现错误将抛出异常，否则返回 results 对象。

`standard.lintFiles(files, [opts], callback)`

检查文件 files globs, opts 可选：

var opts = {
  ignore: [],   // 待忽略的文件 globs，默认值已经够用
  cwd: '',      // 当前工作目录 (默认值： process.cwd())
  fix: false,   // 自动修订
  globals: [],  // 全局变量
  plugins: [],  // eslint 插件
  envs: [],     // eslint 环境
  parser: ''    // js 解析器 (e.g. babel-eslint)
}

callback 参数为 Error 和 results 对象（同上）。

如何为 `standard` 做出贡献？

欢迎！查看 issues 或 PRs，如果没有找到你想要的就提交一个。

想群聊？在 freenode 加入 #standard 频道。

下面是 standard 生态系统中一些重要的包：

standard - 本项目
- standard-engine - 命令行引擎
- eslint-config-standard - standard 使用的 eslint 规则
- eslint-config-standard-jsx - standard (JSX) 使用的 eslint 规则
- eslint-plugin-standard - standard 自定义的 eslint 规则，不是 eslint 的核心
- eslint - standard 使用的验证器
snazzy - 漂亮的输出
standard-www - http://standardjs.com 源码
semistandard - 有分号的 standard，如果你必须用分号的话

还有许多 编辑器插件， 使用 standard 的包，以及 standard 生态系统中的包。

版权

MIT. Copyright (c) Feross Aboukhadijeh.

由 Ivan Yan 翻译，译文采用知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议，意见反馈。

JavaScript 标准风格

一种风格规范全部代码

JavaScript 代码规范，包含检查器和自动格式化工具

规则

目录

安装

用法

聪明的你会这么做

为什么我要用 JavaScript Standard Style?

谁在用 JavaScript Standard Style？

有编辑器插件吗？

Sublime Text

Atom

Visual Studio Code

Vim

Emacs

Brackets

WebStorm (PhpStorm, IntelliJ, RubyMine, JetBrains, etc.)

有 readme 徽章吗？

我不同意规则 X，你可以修改它吗？

但是并没有真正的 web 标准！

有自动格式化工具吗？

如何忽略文件？

如何隐藏某个警告？

我使用的库污染了全局空间，怎么阻止 “variable is not defined” 错误？

我可以使用实验性质 JavaScript (ES Next) 功能吗？

我可以使用 JavaScript 变体吗，比如 Flow？

Mocha, Jasmine, QUnit 等测试框架呢？

Web Workers 呢？

可以检查 Markdown 或 HTML 文件中的代码吗？

有 Git pre-commit 钩子吗？

怎么让输出多彩美观？

有 Node.js API 吗？

standard.lintText(text, [opts], callback)

results = standard.lintTextSync(text, [opts])

standard.lintFiles(files, [opts], callback)

如何为 standard 做出贡献？

版权

有 Git `pre-commit` 钩子吗？

`standard.lintText(text, [opts], callback)`

`results = standard.lintTextSync(text, [opts])`

`standard.lintFiles(files, [opts], callback)`

如何为 `standard` 做出贡献？