首字母大写注释

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

🔧

此规则报告的一些问题可以通过 --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

/* eslint semi:off */
/* eslint-disable */
/* eslint-enable */
/* istanbul ignore next */
/* jscs:enable */
/* jshint asi:true */
/* global foo */
/* globals foo */
/* exported myVar */
// eslint-disable-line
// eslint-disable-next-line
// https://github.com

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

选项

此规则有两个选项：字符串值 "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" 选项意味着此规则将报告任何以小写字母开头的注释。这是此规则的默认配置。

请注意，配置注释和以 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

/* eslint semi:off */
/* eslint-disable */
/* eslint-enable */
/* istanbul ignore next */
/* jscs:enable */
/* jshint asi:true */
/* global foo */
/* globals foo */
/* exported myVar */
// eslint-disable-line
// eslint-disable-next-line
// https://github.com

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

`"从不"`

使用 "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 意味着代码中间的注释（在与注释开头相同的行上有一个标记，以及在与注释结尾相同的行上有一个标记）不会被此规则报告。

将 "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 中引入。

资源

编辑此页面