capitalized-comments

强制或禁止注释首字母大写

🔧

此规则报告的某些问题可以通过 --fix 命令行选项自动修复

❄️

此规则目前处于冻结状态，不接受功能请求。

注释对于为未来的开发者留下信息非常有用。为了使这些信息有用且不分散注意力，有时希望注释遵循特定的风格。注释格式风格的一个要素是注释的第一个单词应该是大写还是小写。

一般来说，没有哪种注释风格比其他风格更有效或更无效，但许多开发者会同意，一致的风格可以提高项目的可维护性。

规则详情

此规则旨在在您的代码库中强制执行一致的注释风格，具体而言，通过要求或禁止将大写字母作为注释中第一个单词的字符。当使用非大小写字母时，此规则不会发出警告。

默认情况下，此规则将要求注释的开头使用非小写字母。

此规则的错误代码示例

在 Playground 中打开

/* eslint capitalized-comments: ["error"] */

// lowercase comment

1
2
3
4

此规则的正确代码示例

在 Playground 中打开

/* eslint capitalized-comments: error */

// Capitalized comment

// 1. Non-letter at beginning of comment

// 丈 Non-Latin character at beginning of comment

/* istanbul ignore next */
/* jscs:enable */
/* jshint asi:true */
/* global foo */
/* globals foo */
/* exported myVar */
// https://github.com

/* eslint semi:2 */
/* eslint-disable */
foo
/* eslint-enable */
// eslint-disable-next-line
baz
bar // eslint-disable-line

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

选项

此规则有两个选项：一个字符串值 "always" 或 "never"，用于确定是否应要求或禁止注释的第一个单词大写，以及一个可选的对象，其中包含更多规则的配置参数。

以下是支持的对象选项

ignorePattern：一个字符串，表示应该被此规则忽略的单词的正则表达式模式。如果注释的第一个单词与该模式匹配，则此规则将不会报告该注释。
- 请注意，以下单词始终被此规则忽略：["jscs", "jshint", "eslint", "istanbul", "global", "globals", "exported"]。
ignoreInlineComments：如果此项为 true，则该规则不会报告代码中间的注释。默认情况下，此项为 false。
ignoreConsecutiveComments：如果此项为 true，则只要注释紧跟在另一个注释之后，该规则就不会报告违反规则的注释。默认情况下，此项为 false。

这是一个配置示例

{
    "capitalized-comments": [
        "error",
        "always",
        {
            "ignorePattern": "pragma|ignored",
            "ignoreInlineComments": true
        }
    ]
}
1
2
3
4
5
6
7
8
9
10

`"always"`

使用 "always" 选项意味着此规则将报告任何以小写字母开头的注释。这是此规则的默认配置。

请注意，配置注释和以 URL 开头的注释永远不会被报告。

此规则的错误代码示例

在 Playground 中打开

/* eslint capitalized-comments: ["error", "always"] */

// lowercase comment

1
2
3
4

此规则的正确代码示例

在 Playground 中打开

/* eslint capitalized-comments: ["error", "always"] */

// Capitalized comment

// 1. Non-letter at beginning of comment

// 丈 Non-Latin character at beginning of comment

/* istanbul ignore next */
/* jscs:enable */
/* jshint asi:true */
/* global foo */
/* globals foo */
/* exported myVar */
// https://github.com

/* eslint semi:2 */
/* eslint-disable */
foo
/* eslint-enable */
// eslint-disable-next-line
baz
bar // eslint-disable-line

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

`"never"`

使用 "never" 选项意味着此规则将报告任何以大写字母开头的注释。

使用 "never" 选项的错误代码示例

在 Playground 中打开

/* eslint capitalized-comments: ["error", "never"] */

// Capitalized comment

1
2
3
4

使用 "never" 选项的正确代码示例

在 Playground 中打开

/* eslint capitalized-comments: ["error", "never"] */

// lowercase comment

// 1. Non-letter at beginning of comment

// 丈 Non-Latin character at beginning of comment

1
2
3
4
5
6
7
8

`ignorePattern`

ignorePattern 对象接受一个字符串值，该值用作应用于注释第一个单词的正则表达式。

"ignorePattern" 选项设置为 "pragma" 的正确代码示例

在 Playground 中打开

/* eslint capitalized-comments: ["error", "always", { "ignorePattern": "pragma" }] */

function foo() {
    /* pragma wrap(true) */
}

1
2
3
4
5
6

`ignoreInlineComments`

将 ignoreInlineComments 选项设置为 true 意味着代码中间的注释（注释开头所在的行上有 token，注释结尾所在的行上有另一个 token）将不会被此规则报告。

"ignoreInlineComments" 选项设置为 true 的正确代码示例

在 Playground 中打开

/* eslint capitalized-comments: ["error", "always", { "ignoreInlineComments": true }] */

function foo(/* ignored */ a) {
}

1
2
3
4
5

`ignoreConsecutiveComments`

如果将 ignoreConsecutiveComments 选项设置为 true，则只要注释紧跟在另一个注释之后，否则违反规则的注释将不会被报告。这可以应用多次。

ignoreConsecutiveComments 设置为 true 的正确代码示例

在 Playground 中打开

/* eslint capitalized-comments: ["error", "always", { "ignoreConsecutiveComments": true }] */

foo();
// This comment is valid since it has the correct capitalization.
// this comment is ignored since it follows another comment,
// and this one as well because it follows yet another comment.

bar();
/* Here is a block comment which has the correct capitalization, */
/* but this one is ignored due to being consecutive; */
/*
 * in fact, even if any of these are multi-line, that is fine too.
 */
1
2
3
4
5
6
7
8
9
10
11
12
13

ignoreConsecutiveComments 设置为 true 的错误代码示例

在 Playground 中打开

/* eslint capitalized-comments: ["error", "always", { "ignoreConsecutiveComments": true }] */

foo();
// this comment is invalid, but only on this line.
// this comment does NOT get reported, since it is a consecutive comment.
1
2
3
4
5

为行注释和块注释使用不同的选项

如果您希望对行注释和块注释使用不同的配置，则可以使用两个不同的对象配置来实现（请注意，大小写选项将对行注释和块注释保持一致强制执行）

{
    "capitalized-comments": [
        "error",
        "always",
        {
            "line": {
                "ignorePattern": "pragma|ignored",
            },
            "block": {
                "ignoreInlineComments": true,
                "ignorePattern": "ignored"
            }
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

具有不同行注释和块注释配置的错误代码示例

在 Playground 中打开

/* eslint capitalized-comments: ["error", "always", { "block": { "ignorePattern": "blockignore" } }] */

// capitalized line comment, this is incorrect, blockignore does not help here
/* lowercased block comment, this is incorrect too */

1
2
3
4
5

具有不同行注释和块注释配置的正确代码示例

在 Playground 中打开

/* eslint capitalized-comments: ["error", "always", { "block": { "ignorePattern": "blockignore" } }] */

// Uppercase line comment, this is correct
/* blockignore lowercase block comment, this is correct due to ignorePattern */

1
2
3
4
5

何时不使用

如果您不关心代码库中注释的语法风格，则可以禁用此规则。

兼容性

JSCS: requireCapitalizedComments
JSCS: disallowCapitalizedComments

版本

此规则在 ESLint v3.11.0 中引入。

资源

编辑此页