spaced-comment

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

一些风格指南要求在注释的初始 // 或 /* 后立即加上空格，或者禁止这样做。 在 // 或 /* 之后加上空格可以让注释中的文本更易于阅读。 另一方面，如果不必在 // 或 /* 后立即加空格，注释代码会更容易。

🌐 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"。

  • 如果 "always"，那么 // 或 /* 后必须跟至少一个空格。
  • 如果 "never"，则后面不应该有空格。

• 此规则还可以接受第二个选项，即包含以下任意键的对象："exceptions" 和 "markers"。

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

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

  • "markers" 值是一个字符串模式数组，被认为是 docblock 风格注释的标记，例如一个额外的 /，用于表示被 doxygen、vsdoc 等读取的文档，这些文档必须包含额外的字符。"markers" 数组将无论第一个参数的值如何都适用，例如 "always" 或 "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"，那么 /* 必须后面至少跟一个空格，*/ 必须前面至少有一个空格。
• 如果 "balanced": true 和 "never"，那么在 /* 之后或 */ 之前不应该有空格。
• 如果 "balanced": false，则不会强制平衡空白。

"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

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

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

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

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

/* 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 中引入。

资源

• 规则源码
• 测试源码