README-zhcn.md

JavaScript Standard Style

Sponsored by        

English • Español (Latinoamérica) • Français • Bahasa Indonesia • Italiano (Italian) • 日本語 (Japanese) • 한국어 (Korean) • Português (Brasil) • 简体中文 (Simplified Chinese) • 繁體中文 (Taiwanese Mandarin)

JavaScript 代码规范，自带 linter & 代码自动修正

本工具通过以下三种方式为你（及你的团队）节省大量时间：

• 无须配置。 史上最便捷的统一代码风格的方式，轻松拥有。
• 自动代码格式化。 只需运行 standard --fix 从此和脏乱差的代码说再见。
• 提前发现风格及程序问题。 减少代码审查过程中反反复复的修改过程，节约时间。

无须犹豫。再也不用维护 .eslintrc, .jshintrc, or .jscsrc 。开箱即用。

安装：

npm install standard --save-dev

细则

• 使用两个空格 – 进行缩进
• 字符串使用单引号 – 需要转义的地方除外
• 不再有冗余的变量 – 这是导致 大量 bug 的源头!
• 无分号 – 这没什么不好。不骗你！
• 行首不要以 (, [, or ` 开头
  • 这是省略分号时唯一会造成问题的地方 – 工具里已加了自动检测！
  • 详情
• 关键字后加空格 if (condition) { ... }
• 函数名后加空格 function name (arg) { ... }
• 坚持使用全等 === 摒弃 == 一但在需要检查 null || undefined 时可以使用 obj == null。
• 一定要处理 Node.js 中错误回调传递进来的 err 参数。
• 使用浏览器全局变量时加上 window 前缀 – document 和 navigator 除外
  • 避免无意中使用到了这些命名看上去很普通的全局变量， open, length, event 还有 name。
• 查看更多 – 为何不试试 standard 规范呢！

说了那么多，看看这个遵循了 Standard 规范的示例文件 中的代码吧。或者，这里还有一大波使用了此规范的项目 代码可供参考。

目录

• 上手
  • 安装
  • 使用
  • 如果你聪明的话会这样做
• FAQ
  • 为何要使用 JavaScript Standard 规范？
  • 谁在用 JavaScript Standard 规范？
  • 有现成的编辑器插件吗？
  • 有专属徽章可以用来放到项目的 README 文件中吗？
  • 如果我不同意某条规则，可以改吗？
  • 毕竟这不是一份正式的 Web 规范啊！
  • 有自动格式化工具么？
  • 如何排除某些文件？
  • 如何隐藏某类警告？
  • 使用的三方插件向全局暴露了变量，如何避免 "variable is not defined" 的错误提示？
  • 如何才能使用处于实验阶段的 JavaScript 特性（譬如 ES Next）？
  • 我能使用其他 JavaScript 变种吗，例如 Flow？
  • 如何与 Mocha，Jasmine 和 QUnit 这些测试工具搭配工作?
  • Web Workers 有考虑过么？
  • Markdown 或者 HTML 文件中的代码能检查到吗？
  • 有为 git 添加 pre-commit 钩子么？
  • 怎样使输出好看些，带颜色？
  • 有相关的 Node.js API 没？
  • 如何参与到 standard 规范中来？
• 协议

安装

使用本规范最便捷的方式是全局安装，运行：

$ npm install standard --global

或者非全局的方式，针对某个项目进行安装：

$ npm install standard --save-dev

注意：运行以上命令的前提是已经安装了 Node.js 和 npm 。

使用

安装完就可以开心使用了。最简单的使用场景是检查项目内所有的 JavaScript 文件：

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

可以跟上 glob 形式的路径参数，但记得带引号以确保 standard 工具正确解析，否则会被命令行解析。

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

注意： standard 默认查找 **/*.js, **/*.jsx 所匹配到的文件。

如果你聪明的话会这样做

1. 添加配置到 package.json

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

2. 这样检查工作就会在运行 npm test 自动进行

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

3. 从此告别在提 PR 时的代码风格的问题！

为何要使用 JavaScript Standard 规范？

本规范特点之一是简洁。谁也不想为每个项目维护一份有成百上千行语句的代码风格配置文件。有此规范就够了。

本工具通过以下三种方式为你（及你的团队）节省大量时间：

• 无须配置。 史上最便捷的统一代码风格的方式，轻松拥有。
• 自动的代码格式化。 只需运行 standard --fix 从此和脏乱差的代码说再见。
• 提前发现风格及程序问题。 减少代码审查时的反反复复修改过程，节约时间。

一旦使用 standard 规范表明代码的简明性及社区的约定要高于个人的编码风格。这不一定100%适用于所有项目和多元的编程文化，但开源项目代码容易受到新手的影响。把规范讲明，严格执行对于项目的长远维护不无裨益。

谁在用 JavaScript Standard 规范？

我们是有群众基础的！

	Your logo here	Your logo here	Your logo here

除公司组织外，很多个人也在项目中使用，这里就不一一罗列了。

并且 standard 在 GitHub 的代码检查类工具 展示列表中也排名第一。

有现成的编辑器插件吗？

首先安装 standard。剩下的就是不同编译器安装对应的插件：

Sublime Text

通过 Package Control，安装 SublimeLinter 和 SublimeLinter-contrib-standard。

如果想要保存时自动格式化，还需安装 StandardFormat。

Atom

安装 linter-js-standard。

如果想要保存时自动格式化，还需安装 standard-formatter。安装 standardjs-snippets 可以获得 snippets 特性。

Visual Studio Code

安装 vscode-standard（已经包含了自动格式化）。

安装 vscode-standardjs-snippets 以获得 JS snippets。安装 vscode-react-standard 以获得 React snippets。

Vim

安装 Syntastic 并添加如下配置到 .vimrc：

let g:syntastic_javascript_checkers = ['standard']

如果想要保存时自动格式化，添加以下配置到 .vimrc：

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

Emacs

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

Brackets

插件中搜索 "Standard Code Style" 然后点击 "Install"。

WebStorm (PhpStorm, IntelliJ, RubyMine, JetBrains 等 jetbrains 全家桶系列)

WebStorm 最近宣布在其 IDE 中 自带 standard 规范。

但是如果你仍然想自己动手配置，那么请看此教程。此教程适用于 JetBrains 全家桶，包括 PhpStorm、IntelliJ、RubyMine 等。

有专属徽章可以用来放到项目的 README 文件中吗？

必需的！如果你的项目使用了 standard 规范，可以任选一个下面的徽章放入项目中来进行展示。

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

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

如果我不同意某条规则，可以改吗？

不行。制定这套 standard 规范的目的就是让大家都不必再花时间浪费在无谓的代码风格之争上面了。关于缩进该用制表符还是空格这个问题已经争论了很久了，永远也没有答案。争论这个都可以把需求提前写完了。遵循 standard 规范，你就不用再犹豫了，毕竟不管怎样争论总归会选择一种风格的。希望大家也能在个人语义和普适价值上做一个权衡。

如果你非要自己去配置成百上千项的 ESLint 规则，那你可以直接使用 eslint-config-standard 来将个人配置包装在上层。

小贴士：选择 standard 然后保持吧。把时间留下来解决其他有意义的问题！(^____^)/

毕竟这不是一份正式的 Web 规范啊！

确实！这份规范不隶属于任何官方组织，所以才叫 standard/standard 而不是 ECMA/standard 嘛。

而 standard (标准) 一词在这里不局限于 “web 标准” :-) 。 举个例子：

• 这个模块帮助我们将代码维持在一个高的水准（standard of quality）
• 这个模块确定项目中的新手遵循一些基本的样式规范（style standards）

有自动格式化工具么？

当然！你可以使用 standard --fix 来纠正大部分的代码问题。

standard --fix 可以修正大部分约定俗成的问题，但有些错误（譬如忘记了错误处理）只能手动去修复了。

为了使用方便，standard 会在检测到有能够自动被修复的问题的时候，给出相应的提示 "运行 standard --fix 来自动修正一些问题"。

如何排除某些文件？

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 代码规范底层使用的是 ESLint。所以如果你想隐藏某些警告，方法和使用 ESLint 时一样。

对某一行禁用所有规则：

file = 'I know what I am doing' // eslint-disable-line

或者，只禁用 "no-use-before-define" 这条规则：

file = 'I know what I am doing' // 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）。这些变量或方法即没有定义，也没有被 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 支持自定义 JavaScript 解析器。添加自定义解析器前请思考一下必要性。

从 npm 安装并使用自定义的解析器（示例：npm install @babel/eslint-parser）：

$ standard --parser @babel/eslint-parser

或者将其添加到 package.json 配置中：

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

如果全局安装（npm install standard --global）了 standard 的话，那么请确保 @babel/eslint-parser 也用 npm install @babel/eslint-parser --global 全局安装。

我能使用其他 JavaScript 变种吗，例如 Flow？

同样地，想要使用一个 JS 变种之前，先考虑添加和使用它所带来的复杂度看是否值得这么去做。

standard 支持 ESLint 插件。在 standard 处理代码前，使用任何一个插件来将代码编译成合法的 JS 即可。 从 npm 安装一个自定义的解析器 (示例：npm install eslint-plugin-flowtype) 然后运行：

$ standard --plugin flowtype

或者添加到package.json:

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

如果全局安装（npm install standard --global）了 standard 的话，那么请确保 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 npm 包中查到。

注意: env 与 envs 用哪个都一样。

Web Workers 有考虑过么？

添加以下注释到文件头部：

/* eslint-env serviceworker */

这样可以让 standard 知道 self 是 web worker 中的全局变量（同时也让人更容易看懂）。

Markdown 或者 HTML 文件中的代码能检查到吗？

可以使用 standard-markdown 来检查 Markdown 里的区位码。

此外，也有 ESLint 插件可以检查 Markdown、HTML 等其他类型文件中的代码：

检查 Markdown 文件中的代码，可以用这个 ESLint 插件：

$ npm install eslint-plugin-markdown

然后运行以下命令来检查文件代码块中的代码：

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

HTML 文件可以下面这个插件：

$ npm install eslint-plugin-html

然后运行以下命令来检查包含在 <script> 标签中的代码：

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

有为 git 添加 pre-commit 钩子么？

这个问题问得好！

#!/bin/bash

# 确保将要提交的所有 JavaScript 代码通过 standard 规范的检查
function xargs-r() {
  # Portable version of "xargs -r". The -r flag is a GNU extension that
  # prevents xargs from running if there are no input files.
  if IFS= read -r -d $'\n' path; then
    echo "$path" | cat - | xargs "$@"
  fi
}
git diff --name-only --cached --relative | grep '\.jsx\?$' | sed 's/[^[:alnum:]]/\\&/g' | xargs-r -E '' -t standard
if [[ $? -ne 0 ]]; then
  echo 'JavaScript Standard Style errors were detected. Aborting commit.'
  exit 1
fi

怎样使输出好看些，带颜色？

自带的输出信息简洁原始，如果想要炫酷好看，安装 snazzy：

$ npm install snazzy

然后运行：

$ standard | snazzy

还有 standard-tap、 standard-json、 standard-reporter 和 standard-summary 这些类似的工具。

有相关的 Node.js API 没？

有！

async standard.lintText(text, [opts])

检查传入的 text。需要提供一个 opts 配置参数：

{
  // unique to lintText
  filename: '',         // path of file containing the text being linted

  // common to lintText and lintFiles
  cwd: '',              // current working directory (default: process.cwd())
  fix: false,           // automatically fix problems
  extensions: [],       // file extensions to lint (has sane defaults)
  globals: [],          // custom global variables to declare
  plugins: [],          // custom eslint plugins
  envs: [],             // custom eslint environment
  parser: '',           // custom js parser (e.g. babel-eslint)
  usePackageJson: true, // use options from nearest package.json?
  useGitIgnore: true    // use file ignore patterns from .gitignore?
}

如果 package.json 有相应配置也会自动被读取到。

包含结果的 results 包含如下属性：

const results = {
  results: [
    {
      filePath: '',
      messages: [
        { ruleId: '', message: '', line: 0, column: 0 }
      ],
      errorCount: 0,
      warningCount: 0,
      output: '' // fixed source code (only present with {fix: true} option)
    }
  ],
  errorCount: 0,
  warningCount: 0
}

async standard.lintFiles(files, [opts])

检查以 glob 形式指定的 files 参数所匹配到的所有文件。可以传入一个 opts 配置参数：

{
  // unique to lintFiles
  ignore: [],           // file globs to ignore (has sane defaults)

  // common to lintText and lintFiles
  cwd: '',              // current working directory (default: process.cwd())
  fix: false,           // automatically fix problems
  extensions: [],       // file extensions to lint (has sane defaults)
  globals: [],          // custom global variables to declare
  plugins: [],          // custom eslint plugins
  envs: [],             // custom eslint environment
  parser: '',           // custom js parser (e.g. babel-eslint)
  usePackageJson: true, // use options from nearest package.json?
  useGitIgnore: true    // use file ignore patterns from .gitignore?
}

回调同上。

如何参与到 standard 规范中来？

欢迎参与进来！逛逛 issues 或者 PRs 页面，如果发现没有找到想要的问题可以自己提一个。

来 freenode 的 #standard 频道与其他人一起聊天讨论！

以下是一些 standard 生态里比较重要的包：

• standard - 本仓库
  • standard-engine - 一个 eslint 命令行引擎
  • eslint-config-standard -standard 规范的 eslint 检查器
  • eslint-config-standard-jsx - standard (JSX) 的 eslint 规范
  • eslint-plugin-standard - standard 规范自定义的 eslint 规则（不在 eslint 核心规则里面）
  • eslint - standard 基于它来实现的
• snazzy - 美化输出
• standard-www - https://standardjs.com 站点的源码
• semistandard - standard 规范带分号的版本（如果你需要的话）

还有很多 编辑器插件、一个 **使用 standard 规范开发的 npm 包的列表、还有一分非常棒的 standard 生态中所使用到的包**的列表。

协议

MIT. Copyright (c) Feross Aboukhadijeh.