capitalized-comments

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

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

¥Comments are useful for leaving information for future developers. In order for that information to be useful and not distracting, it is sometimes desirable for comments to follow a particular style. One element of comment formatting styles is whether the first word of a comment should be capitalized or lowercase.

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

¥In general, no comment style is any more or less valid than any others, but many developers would agree that a consistent style can improve a project’s maintainability.

规则详情

¥Rule Details

此规则旨在在你的代码库中强制使用一致的注释样式，特别是通过要求或禁止将大写字母作为注释中的第一个单词字符。当使用非大写字母时，此规则不会触发警告。

¥This rule aims to enforce a consistent style of comments across your codebase, specifically by either requiring or disallowing a capitalized letter as the first word character in a comment. This rule will not issue warnings when non-cased letters are used.

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

¥By default, this rule will require a non-lowercase letter at the beginning of comments.

此规则的错误代码示例：

¥Examples of incorrect code for this rule:

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

// lowercase comment

1
2
3
4

此规则的正确代码示例：

¥Examples of correct code for this rule:

/* 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

选项

¥Options

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

¥This rule has two options: a string value "always" or "never" which determines whether capitalization of the first word of a comment should be required or forbidden, and optionally an object containing more configuration parameters for the rule.

以下是支持的对象选项：

¥Here are the supported object options:

• ignorePattern：表示此规则应忽略的单词的正则表达式模式的字符串。如果注释的第一个单词与模式匹配，则此规则不会报告该注释。

  ¥ignorePattern: A string representing a regular expression pattern of words that should be ignored by this rule. If the first word of a comment matches the pattern, this rule will not report that comment.

  • 请注意，此规则始终忽略以下单词：["jscs", "jshint", "eslint", "istanbul", "global", "globals", "exported"]。

    ¥Note that the following words are always ignored by this rule: ["jscs", "jshint", "eslint", "istanbul", "global", "globals", "exported"].

• ignoreInlineComments：如果这是 true，则规则不会报告代码中间的注释。默认情况下，这是 false。

  ¥ignoreInlineComments: If this is true, the rule will not report on comments in the middle of code. By default, this is false.

• ignoreConsecutiveComments：如果这是 true，则规则不会报告违反规则的注释，只要该注释紧跟在另一条注释之后。默认情况下，这是 false。

  ¥ignoreConsecutiveComments: If this is true, the rule will not report on a comment which violates the rule, as long as the comment immediately follows another comment. By default, this is false.

这是一个示例配置：

¥Here is an example configuration:

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

"always"

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

¥Using the "always" option means that this rule will report any comments which start with a lowercase letter. This is the default configuration for this rule.

请注意，从不报告以 URL 开头的配置注释和注释。

¥Note that configuration comments and comments which start with URLs are never reported.

此规则的错误代码示例：

¥Examples of incorrect code for this rule:

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

// lowercase comment

1
2
3
4

此规则的正确代码示例：

¥Examples of correct code for this rule:

/* 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" 选项意味着该规则将报告任何以大写字母开头的注释。

¥Using the "never" option means that this rule will report any comments which start with an uppercase letter.

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

¥Examples of incorrect code with the "never" option:

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

// Capitalized comment

1
2
3
4

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

¥Examples of correct code with the "never" option:

/* 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 对象接受一个字符串值，该值用作应用于注释第一个单词的正则表达式。

¥The ignorePattern object takes a string value, which is used as a regular expression applied to the first word of a comment.

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

¥Examples of correct code with the "ignorePattern" option set to "pragma":

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

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

1
2
3
4
5
6

ignoreInlineComments

将 ignoreInlineComments 选项设置为 true 意味着代码中间的注释（与注释开头在同一行的标记，与注释结尾在同一行的另一个标记）将不会被此规则报告.

¥Setting the ignoreInlineComments option to true means that comments in the middle of code (with a token on the same line as the beginning of the comment, and another token on the same line as the end of the comment) will not be reported by this rule.

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

¥Examples of correct code with the "ignoreInlineComments" option set to true:

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

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

1
2
3
4
5

ignoreConsecutiveComments

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

¥If the ignoreConsecutiveComments option is set to true, then comments which otherwise violate the rule will not be reported as long as they immediately follow another comment. This can be applied more than once.

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

¥Examples of correct code with ignoreConsecutiveComments set to true:

/* 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
14

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

¥Examples of incorrect code with ignoreConsecutiveComments set to true:

/* 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

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

¥Using Different Options for Line and Block Comments

如果你希望对行注释和块注释有不同的配置，你可以通过使用两种不同的对象配置来实现（请注意，行注释和块注释将一致地强制执行大写选项）：

¥If you wish to have a different configuration for line comments and block comments, you can do so by using two different object configurations (note that the capitalization option will be enforced consistently for line and block comments):

{
    "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

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

¥Examples of incorrect code with different line and block comment configuration:

/* 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

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

¥Examples of correct code with different line and block comment configuration:

/* 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

何时不使用

¥When Not To Use It

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

¥This rule can be disabled if you do not care about the grammatical style of comments in your codebase.

兼容性

¥Compatibility

• JSCS:requireCapitalizedComments

• JSCS:disallowCapitalizedComments

版本

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

资源

• 规则源码
• 测试源码