capitalized-comments (Rules) - Eslint 中文开发手册

在--fix命令行上的选项可以自动修复一些被这条规则反映的问题。

评论对于为将来的开发者留下信息很有用。为了使这些信息有用且不会分散注意力，有时需要评论遵循特定的风格。评论格式化风格的一个要素是评论的第一个单词是大写还是小写。

一般来说，没有任何评论风格比任何其他评论风格都更有效，但许多开发人员会认同一致的风格可以提高项目的可维护性。

规则细节

此规则旨在贯穿代码库实施一致的评论风格，特别是要求或不允许大写字母作为评论中的第一个单词字符。此规则在使用非封装字母时不会发出警告。

默认情况下，此规则在注释开始时将需要非小写字母。

此规则的错误代码示例：

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

// lowercase comment

此规则的正确代码示例：

// Capitalized comment

// 1. Non-letter at beginning of comment

// 丈 Non-Latin character at beginning of comment

/* eslint semi:off */
/* eslint-env node */
/* 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

选项

此规则有两个选项：一个字符串值"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
        }
    ]
}

"always"

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

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

此规则的错误代码示例：

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

// lowercase comment

此规则的正确代码示例：

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

"never"

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

错误代码的示例"never"：

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

// Capitalized comment

带有以下选项的正确代码示例"never"：

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

// lowercase comment

// 1. Non-letter at beginning of comment

// 丈 Non-Latin character at beginning of comment

ignorePattern

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

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

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

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

ignoreInlineComments

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

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

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

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

ignoreConsecutiveComments

如果ignoreConsecutiveComments选项设置为true，那么只要他们立即遵循另一条评论，就不会报告违反规则的评论。这可以多次应用。

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

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

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

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

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

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

// this comment is invalid, but only on this line.
// this comment does NOT get reported, since it is a consecutive comment.

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

如果您希望对行注释和块注释进行不同的配置，可以使用两种不同的对象配置（请注意，大小写选项将对行注释和块注释执行一致）：

{
    "capitalized-comments": [
        "error",
        "always",
        {
            "line": {
                "ignorePattern": "pragma|ignored",
            },
            "block": {
                "ignoreInlineComments": true,
                "ignorePattern": "ignored"
            }
        }
    ]
}

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

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

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

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

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

何时不使用它

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

兼容性

JSCS：requireCapitalizedComments和disallowCapitalizedComments

版

该规则在ESLint 3.11.0中引入。

资源

规则来源文档来源