ESLint 常用规则

ESLint 通过规则(rules)来描述具体的检查行为，每条规则代表一项代码格式规范。

示例：

我们可以来看下面这条规则：

{

"semi": 2,

"semi": [2, 'always', {"omitLastInOneLineBlock": true}],

}

其中"semi" 是这条规则的名称，表示是否应该在行尾使用分号。"semi" 对应的值可以是一个值或者一个数组：

• 如果为值，在该值为这条规则的错误级别，其他选项为默认。
• 如果为数组，数组中各项都有特定含义，如：数组第一项为该规则的错误级别(level)，数组的其他项为该规则 配置选项(options)。

注释规则

我们可以在文件中使用如下所示的块注释，来临时禁止规则出现警告。

/* eslint-disable */

alert('xkd');

/* eslint-enable */

如果要在整个文件范围内禁止规则出现警告，只需将将 /* eslint-disable */ 块注释放在文件顶部即可：

/* eslint-disable */

alert('xkd');

也对指定的规则启动或禁用警告，如下所示：

/* eslint-disable no-console */

var a = 1;

console.log(a);

/* eslint-enable no-console */

使用行注释或块注释，在某一特定的行上禁用某个指定的规则：

alert('xkd'); // eslint-disable-line no-alert

alert('xkd'); /* eslint-disable-line no-alert */

使用行注释或块注释，在某个特定的行上禁用多个规则：

alert('xkd'); // eslint-disable-line no-alert, quotes, semi

// eslint-disable-next-line no-alert, quotes, semi

alert('xkd');

alert('xkd'); /* eslint-disable-line no-alert, quotes, semi */

/* eslint-disable-next-line no-alert, quotes, semi */

alert('xkd');

错误级别

规则的错误级别分为三级：

• 0 或者"off" ，表示关闭规则。
• 1或者"warn" ，打开规则，并且将规则视为一个警告（并不会导致检查不通过）。
• 2或者"error" ，打开规则，并且将规则视为一个错误 (退出码为1，检查不通过)。

常用规则

与 JavaScript 代码中可能的错误或逻辑错误有关的规则：

no-cond-assign // 禁止条件表达式中出现模棱两可的赋值操作符

no-console // 禁用console

no-constant-condition // 禁止在条件中使用常量表达式

no-debugger // 禁用 debugger

no-dupe-args // 禁止 function 定义中出现重名参数

no-dupe-keys // 禁止对象字面量中出现重复的 key

no-duplicate-case // 禁止出现重复的 case 标签

no-empty // 禁止出现空语句块

no-ex-assign // 禁止对 catch 子句的参数重新赋值

no-extra-boolean-cast // 禁止不必要的布尔转换

no-extra-parens // 禁止不必要的括号

no-extra-semi // 禁止不必要的分号

no-func-assign // 禁止对 function 声明重新赋值

no-inner-declarations // 禁止在嵌套的块中出现变量声明或 function 声明

no-irregular-whitespace // 禁止在字符串和注释之外不规则的空白

no-obj-calls // 禁止把全局对象作为函数调用

no-sparse-arrays // 禁用稀疏数组

no-prototype-builtins // 禁止直接使用Object.prototypes 的内置属性

no-unexpected-multiline // 禁止出现令人困惑的多行表达式

no-unreachable // 禁止在return、throw、continue 和 break语句之后出现不可达代码

use-isnan // 要求使用 isNaN() 检查 NaN

valid-typeof // 强制 typeof 表达式与有效的字符串进行比较

下面这些规则是关于最佳实践的，帮助你避免一些问题：

array-callback-return // 强制数组方法的回调函数中有 return 语句

block-scoped-var // 强制把变量的使用限制在其定义的作用域范围内

complexity // 指定程序中允许的最大环路复杂度

consistent-return // 要求 return 语句要么总是指定返回的值，要么不指定

curly // 强制所有控制语句使用一致的括号风格

default-case // 要求 switch 语句中有 default 分支

dot-location // 强制在点号之前和之后一致的换行

dot-notation // 强制在任何允许的时候使用点号

eqeqeq // 要求使用 === 和 !==

guard-for-in // 要求 for-in 循环中有一个 if 语句

no-alert // 禁用 alert、confirm 和 prompt

no-case-declarations // 不允许在 case 子句中使用词法声明

no-else-return // 禁止 if 语句中有 return 之后有 else

no-empty-function // 禁止出现空函数

no-eq-null // 禁止在没有类型检查操作符的情况下与 null 进行比较

no-eval // 禁用 eval()

no-extra-bind // 禁止不必要的 .bind() 调用

no-fallthrough // 禁止 case 语句落空

no-floating-decimal // 禁止数字字面量中使用前导和末尾小数点

no-implicit-coercion // 禁止使用短符号进行类型转换

no-implicit-globals // 禁止在全局范围内使用 var 和命名的 function 声明

no-invalid-this // 禁止 this 关键字出现在类和类对象之外

no-lone-blocks // 禁用不必要的嵌套块

no-loop-func // 禁止在循环中出现 function 声明和表达式

no-magic-numbers // 禁用魔术数字

no-multi-spaces // 禁止使用多个空格

no-multi-str // 禁止使用多行字符串

no-new // 禁止在非赋值或条件语句中使用 new 操作符

no-new-func // 禁止对 Function 对象使用 new 操作符

no-new-wrappers // 禁止对 String，Number 和 Boolean 使用 new 操作符

no-param-reassign // 不允许对 function 的参数进行重新赋值

no-redeclare // 禁止使用 var 多次声明同一变量

no-return-assign // 禁止在 return 语句中使用赋值语句

no-script-url // 禁止使用 javascript: url

no-self-assign // 禁止自我赋值

no-self-compare // 禁止自身比较

no-sequences // 禁用逗号操作符

no-unmodified-loop-condition // 禁用一成不变的循环条件

no-unused-expressions // 禁止出现未使用过的表达式

no-useless-call // 禁止不必要的 .call() 和 .apply()

no-useless-concat // 禁止不必要的字符串字面量或模板字面量的连接

vars-on-top // 要求所有的 var 声明出现在它们所在的作用域顶部

与使用严格模式和严格模式指令有关规则：

strict // 要求或禁止使用严格模式指令

与变量声明有关规则：

init-declarations // 要求或禁止 var 声明中的初始化

no-catch-shadow // 不允许 catch 子句的参数与外层作用域中的变量同名

no-restricted-globals // 禁用特定的全局变量

no-shadow // 禁止 var 声明 与外层作用域的变量同名

no-undef // 禁用未声明的变量，除非它们在 /global / 注释中被提到

no-undef-init // 禁止将变量初始化为 undefined

no-unused-vars // 禁止出现未使用过的变量

no-use-before-define // 不允许在变量定义之前使用它们

关于Node.js 或 在浏览器中使用CommonJS 的规则：

global-require // 要求 require() 出现在顶层模块作用域中

handle-callback-err // 要求回调函数中有容错处理

no-mixed-requires // 禁止混合常规 var 声明和 require 调用

no-new-require // 禁止调用 require 时使用 new 操作符

no-path-concat // 禁止对 dirname 和 filename进行字符串连接

no-restricted-modules // 禁用指定的通过 require 加载的模块

下面的规则是关于风格指南的，而且是非常主观的

array-bracket-spacing // 强制数组方括号中使用一致的空格

block-spacing // 强制在单行代码块中使用一致的空格

brace-style // 强制在代码块中使用一致的大括号风格

camelcase // 强制使用骆驼拼写法命名约定

comma-spacing // 强制在逗号前后使用一致的空格

comma-style // 强制使用一致的逗号风格

computed-property-spacing // 强制在计算的属性的方括号中使用一致的空格

eol-last // 强制文件末尾至少保留一行空行

func-names // 强制使用命名的 function 表达式

func-style // 强制一致地使用函数声明或函数表达式

indent // 强制使用一致的缩进

jsx-quotes // 强制在 JSX 属性中一致地使用双引号或单引号

key-spacing // 强制在对象字面量的属性中键和值之间使用一致的间距

keyword-spacing // 强制在关键字前后使用一致的空格

linebreak-style // 强制使用一致的换行风格

lines-around-comment // 要求在注释周围有空行

max-depth // 强制可嵌套的块的最大深度

max-len // 强制一行的最大长度

max-lines // 强制最大行数

max-nested-callbacks // 强制回调函数最大嵌套深度

max-params // 强制 function 定义中最多允许的参数数量

max-statements // 强制 function 块最多允许的的语句数量

max-statements-per-line // 强制每一行中所允许的最大语句数量

new-cap // 要求构造函数首字母大写

new-parens // 要求调用无参构造函数时有圆括号

newline-after-var // 要求或禁止 var 声明语句后有一行空行

newline-before-return // 要求 return 语句之前有一空行

newline-per-chained-call // 要求方法链中每个调用都有一个换行符

no-array-constructor // 禁止使用 Array 构造函数

no-continue // 禁用 continue 语句

no-inline-comments // 禁止在代码行后使用内联注释

no-lonely-if // 禁止 if 作为唯一的语句出现在 else 语句中

no-mixed-spaces-and-tabs // 不允许空格和 tab 混合缩进

no-multiple-empty-lines // 不允许多个空行

no-negated-condition // 不允许否定的表达式

no-plusplus // 禁止使用一元操作符 ++ 和 –

no-spaced-func // 禁止 function 标识符和括号之间出现空格

no-trailing-spaces // 禁用行尾空格

no-whitespace-before-property // 禁止属性前有空白

object-curly-newline // 强制花括号内换行符的一致性

object-curly-spacing // 强制在花括号中使用一致的空格

object-property-newline // 强制将对象的属性放在不同的行上

one-var // 强制函数中的变量要么一起声明要么分开声明

one-var-declaration-per-line // 要求或禁止在 var 声明周围换行

operator-assignment // 要求或禁止在可能的情况下要求使用简化的赋值操作符

operator-linebreak // 强制操作符使用一致的换行符

quote-props // 要求对象字面量属性名称用引号括起来

quotes // 强制使用一致的反勾号、双引号或单引号

require-jsdoc // 要求使用 JSDoc 注释

semi // 要求或禁止使用分号而不是 ASI

semi-spacing // 强制分号之前和之后使用一致的空格

sort-vars // 要求同一个声明块中的变量按顺序排列

space-before-blocks // 强制在块之前使用一致的空格

space-before-function-paren // 强制在 function的左括号之前使用一致的空格

space-in-parens // 强制在圆括号内使用一致的空格

space-infix-ops // 要求操作符周围有空格

space-unary-ops // 强制在一元操作符前后使用一致的空格

spaced-comment // 强制在注释中 // 或 /* 使用一致的空格

链接：https://www.9xkd.com/

JSDoc 注释规范

什么是 JSDoc

JSDoc 是一个根据 JavaScript 文件中注释信息，生成 JavaScript 应用程序或模块的API文档的工具。你可以使用 JSDoc 标记如：命名空间，类，方法，方法参数等。从而使开发者能够轻易地阅读代码，掌握代码定义的类和其属性和方法，从而降低维护成本，和提高开发效率。

JSDoc 注释规则

JSDoc注释一般应该放置在方法或函数声明之前，它必须以/ **开始，以便由JSDoc解析器识别。其他任何以/*，/***或者超过3个星号的注释，都将被JSDoc解析器忽略。如下所示：

/**
* 一段简单的 JSDoc 注释。
*/

JSDoc 的注释效果

假如我们有一段这样的代码，没有任何注释，看起来是不是有一定的成本。

function Book(title, author) {
this.title=title;
this.author=author;
}
Book.prototype={
getTitle:function(){
return this.title;
},
setPageNum:function(pageNum){
this.pageNum=pageNum;
}
};

如果使用了 JSDoc 注释该代码后，代码的可阅读性就大大的提高了。

/**
* Book类，代表一个书本.
* @constructor
* @param {string} title - 书本的标题.
* @param {string} author - 书本的作者.
*/
function Book(title, author) {
this.title=title;
this.author=author;
}
Book.prototype={
/**
* 获取书本的标题
* @returns {string|*} 返回当前的书本名称
*/    
getTitle:function(){
return this.title;
},
/**
* 设置书本的页数
* @param pageNum {number} 页数
*/    
setPageNum:function(pageNum){
this.pageNum=pageNum;
}
};

@constructor 构造函数声明注释

@constructor 明确一个函数是某个类的构造函数。

@param 参数注释

我们通常会使用 @param 来表示函数、类的方法的参数，@param 是JSDoc中最常用的注释标签。参数标签可表示一个参数的参数名、参数类型和参数描述的注释。如下所示：

/**
* @param {String} wording 需要说的句子
*/
function say(wording) {
console.log(wording);
}

@return 返回值注释

@return 表示一个函数的返回值，如果函数没有显示指定返回值可不写。如下所示：

/*
* @return {Number} 返回值描述
*/

@example 示例注释

@example 通常用于表示示例代码,通常示例的代码会另起一行编写，如下所示：

/*
* @example
* multiply(3, 2); 
*/

其他常用注释

• @overview 对当前代码文件的描述。
• @copyright 代码的版权信息。
• @author <name> [<emailAddress>] 代码的作者信息。
• @version 当前代码的版本。

更多参考

如果想了解更多的 JSDoc 注释的内容，可参考下面的链接。