spaced-comment

在注释中的 // 或 /* 之后强制执行一致的间距

此规则在 ESLint v8.53.0 中已弃用。请在 @stylistic/eslint-plugin-js 中使用 相应的规则。

¥This rule was deprecated in ESLint v8.53.0. Please use the corresponding rule in @stylistic/eslint-plugin-js.

一些风格指南要求或不允许在注释的初始 // 或 /* 之后立即使用空格。// 或 /* 之后的空格使阅读注释中的文本更容易。另一方面，注释掉代码更容易，无需在 // 或 /* 之后放置空格。

¥Some style guides require or disallow a whitespace immediately after the initial // or /* of a comment. Whitespace after the // or /* makes it easier to read text in comments. On the other hand, commenting out code is easier without having to put a whitespace right after the // or /*.

规则详情

¥Rule Details

此规则将强制注释 // 或 /* 开始后的间距保持一致。它还为各种文档样式提供了几个例外。

¥This rule will enforce consistency of spacing after the start of a comment // or /*. It also provides several exceptions for various documentation styles.

选项

¥Options

该规则有两个选项。

¥The rule takes two options.

• 第一个是一个字符串，它可以是 "always" 或 "never"。默认值为 "always"。

  ¥The first is a string which be either "always" or "never". The default is "always".

  • 如果是 "always"，那么 // 或 /* 必须后跟至少一个空格。

    ¥If "always" then the // or /* must be followed by at least one whitespace.

  • 如果 "never" 那么后面应该没有空格。

    ¥If "never" then there should be no whitespace following.

• 此规则还可以采用第二个选项，即具有以下任何键的对象："exceptions" 和 "markers"。

  ¥This rule can also take a 2nd option, an object with any of the following keys: "exceptions" and "markers".

  • "exceptions" 值是一个字符串模式数组，被视为规则的例外。当模式从注释的开头开始并重复到行尾或 */ 如果注释是单行注释时，该规则不会触发警告。请注意，如果第一个参数是 "never"，则忽略异常。

    ¥The "exceptions" value is an array of string patterns which are considered exceptions to the rule. The rule will not warn when the pattern starts from the beginning of the comment and repeats until the end of the line or */ if the comment is a single line comment. Please note that exceptions are ignored if the first argument is "never".

  "spaced-comment": ["error", "always", { "exceptions": ["-", "+"] }]
  1
  

  • "markers" 值是一个字符串模式数组，被认为是 docblock 样式注释的标记，例如附加的 /，用于表示 doxygen、vsdoc 等必须具有附加字符的文档读取。无论第一个参数的值如何，"markers" 数组都将适用，例如 "always" 或 "never"。

    ¥The "markers" value is an array of string patterns which are considered markers for docblock-style comments, such as an additional /, used to denote documentation read by doxygen, vsdoc, etc. which must have additional characters. The "markers" array will apply regardless of the value of the first argument, e.g. "always" or "never".

  "spaced-comment": ["error", "always", { "markers": ["/"] }]
  1
  

标记和异常之间的区别在于，标记只出现在注释的开头，而异常可以出现在注释字符串的任何位置。

¥The difference between a marker and an exception is that a marker only appears at the beginning of the comment whereas exceptions can occur anywhere in the comment string.

你还可以为块和行注释定义单独的例外和标记。"block" 对象可以有一个附加键 "balanced"，一个布尔值，指定内联块注释是否应该具有平衡间距。默认值为 false。

¥You can also define separate exceptions and markers for block and line comments. The "block" object can have an additional key "balanced", a boolean that specifies if inline block comments should have balanced spacing. The default value is false.

• 如果 "balanced": true 和 "always"，则 /* 必须后跟至少一个空格，而 */ 必须至少有一个空格。

  ¥If "balanced": true and "always" then the /* must be followed by at least one whitespace, and the */ must be preceded by at least one whitespace.

• 如果 "balanced": true 和 "never"，那么 /* 之后或 */ 之前不应有空格。

  ¥If "balanced": true and "never" then there should be no whitespace following /* or preceding */.

• 如果 "balanced": false 则不强制执行平衡空格。

  ¥If "balanced": false then balanced whitespace is not enforced.

"spaced-comment": ["error", "always", {
    "line": {
        "markers": ["/"],
        "exceptions": ["-", "+"]
    },
    "block": {
        "markers": ["!"],
        "exceptions": ["*"],
        "balanced": true
    }
}]
1
2
3
4
5
6
7
8
9
10
11

always

使用 "always" 选项的此规则的错误代码示例：

¥Examples of incorrect code for this rule with the "always" option:

/*eslint spaced-comment: ["error", "always"]*/

//This is a comment with no whitespace at the beginning

/*This is a comment with no whitespace at the beginning */
1
2
3
4
5

/* eslint spaced-comment: ["error", "always", { "block": { "balanced": true } }] */
/* This is a comment with whitespace at the beginning but not the end*/
1
2

使用 "always" 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the "always" option:

/* eslint spaced-comment: ["error", "always"] */

// This is a comment with a whitespace at the beginning

/* This is a comment with a whitespace at the beginning */

/*

 * This is a comment with a whitespace at the beginning
 */

/*
This comment has a newline
*/
1
2
3
4
5
6
7
8
9
10
11
12
13
14

/* eslint spaced-comment: ["error", "always"] */

/**

* I am jsdoc
*/
1
2
3
4
5
6

never

使用 "never" 选项的此规则的错误代码示例：

¥Examples of incorrect code for this rule with the "never" option:

/*eslint spaced-comment: ["error", "never"]*/

// This is a comment with a whitespace at the beginning

/* This is a comment with a whitespace at the beginning */

/* \nThis is a comment with a whitespace at the beginning */
1
2
3
4
5
6
7

/*eslint spaced-comment: ["error", "never", { "block": { "balanced": true } }]*/
/*This is a comment with whitespace at the end */
1
2

使用 "never" 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the "never" option:

/*eslint spaced-comment: ["error", "never"]*/

/*This is a comment with no whitespace at the beginning */
1
2
3

/*eslint spaced-comment: ["error", "never"]*/

/**

* I am jsdoc
*/
1
2
3
4
5
6

exceptions

此规则的错误代码示例（"always" 选项与 "exceptions" 结合使用）：

¥Examples of incorrect code for this rule with the "always" option combined with "exceptions":

/* eslint spaced-comment: ["error", "always", { "block": { "exceptions": ["-"] } }] */

//--------------
// Comment block
//--------------
1
2
3
4
5

/* eslint spaced-comment: ["error", "always", { "exceptions": ["-", "+"] }] */

//------++++++++
// Comment block
//------++++++++
1
2
3
4
5

/* eslint spaced-comment: ["error", "always", { "exceptions": ["-", "+"] }] */

/*------++++++++*/
/* Comment block */
/*------++++++++*/
1
2
3
4
5

/* eslint spaced-comment: ["error", "always", { "line": { "exceptions": ["-+"] } }] */

/*-+-+-+-+-+-+-+*/
// Comment block
/*-+-+-+-+-+-+-+*/
1
2
3
4
5

/* eslint spaced-comment: ["error", "always", { "block": { "exceptions": ["*"] } }] */

/******** COMMENT *******/
1
2
3

使用 "always" 选项与 "exceptions" 组合的此规则的正确代码示例：

¥Examples of correct code for this rule with the "always" option combined with "exceptions":

/* eslint spaced-comment: ["error", "always", { "exceptions": ["-"] }] */

//--------------
// Comment block
//--------------
1
2
3
4
5

/* eslint spaced-comment: ["error", "always", { "line": { "exceptions": ["-"] } }] */

//--------------
// Comment block
//--------------
1
2
3
4
5

/* eslint spaced-comment: ["error", "always", { "exceptions": ["*"] }] */

/****************

 * Comment block
 ****************/
1
2
3
4
5
6

/* eslint spaced-comment: ["error", "always", { "exceptions": ["-+"] }] */

//-+-+-+-+-+-+-+
// Comment block
//-+-+-+-+-+-+-+

/*-+-+-+-+-+-+-+*/
// Comment block
/*-+-+-+-+-+-+-+*/
1
2
3
4
5
6
7
8
9

/* eslint spaced-comment: ["error", "always", { "block": { "exceptions": ["-+"] } }] */

/*-+-+-+-+-+-+-+*/
// Comment block
/*-+-+-+-+-+-+-+*/
1
2
3
4
5

/* eslint spaced-comment: ["error", "always", { "block": { "exceptions": ["*"] } }] */

/***************/

/********
COMMENT
*******/
1
2
3
4
5
6
7

markers

此规则的错误代码示例（"always" 选项与 "markers" 结合使用）：

¥Examples of incorrect code for this rule with the "always" option combined with "markers":

/* eslint spaced-comment: ["error", "always", { "markers": ["/"] }] */

///This is a comment with a marker but without whitespace
1
2
3

/*eslint spaced-comment: ["error", "always", { "block": { "markers": ["!"], "balanced": true } }]*/
/*! This is a comment with a marker but without whitespace at the end*/
1
2

/*eslint spaced-comment: ["error", "never", { "block": { "markers": ["!"], "balanced": true } }]*/
/*!This is a comment with a marker but with whitespace at the end */
1
2

使用 "always" 选项与 "markers" 组合的此规则的正确代码示例：

¥Examples of correct code for this rule with the "always" option combined with "markers":

/* eslint spaced-comment: ["error", "always", { "markers": ["/"] }] */

/// This is a comment with a marker
1
2
3

/*eslint spaced-comment: ["error", "never", { "markers": ["!<"] }]*/

//!<This is a line comment with a marker

/*!<this is a block comment with a marker
subsequent lines are ignored
*/
1
2
3
4
5
6
7

/* eslint spaced-comment: ["error", "always", { "markers": ["global"] }] */

/*global ABC*/
1
2
3

相关规则

• spaced-line-comment

版本

此规则是在 ESLint v0.23.0 中引入。

资源

• 规则源码
• 测试源码