capitalized-comments

強制或禁止註解的第一個字母大寫

註解對於為未來的開發人員留下資訊很有用。為了讓這些資訊有用且不分散注意力，有時希望註解遵循特定的風格。註解格式化風格的一個要素是註解的第一個單字應該大寫還是小寫。

一般來說，沒有任何註解風格比其他風格更有效或更無效，但許多開發人員會同意，一致的風格可以提高專案的可維護性。

規則詳情

此規則旨在強制在您的程式碼庫中保持一致的註解風格，特別是透過要求或禁止以大寫字母作為註解中的第一個單字字元。當使用非大小寫字母時，此規則不會發出警告。

預設情況下，此規則會要求註解開頭使用非小寫字母。

此規則的錯誤程式碼範例

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

// lowercase comment

1
2
3
4

此規則的正確程式碼範例

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

使用 "always" 選項表示此規則會回報任何以小寫字母開頭的註解。這是此規則的預設設定。

請注意，永遠不會回報設定註解和以 URL 開頭的註解。

此規則的錯誤程式碼範例

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

// lowercase comment

1
2
3
4

此規則的正確程式碼範例

/* 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" 選項表示此規則會回報任何以大寫字母開頭的註解。

使用 "never" 選項的錯誤程式碼範例

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

// Capitalized comment

1
2
3
4

使用 "never" 選項的正確程式碼範例

/* 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" 的正確程式碼範例

/* 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 的正確程式碼範例

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

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

1
2
3
4
5

ignoreConsecutiveComments

如果將 ignoreConsecutiveComments 選項設定為 true，則只要註解緊接在另一個註解之後，否則違反規則的註解就不會被回報。這可以多次套用。

ignoreConsecutiveComments 設定為 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

ignoreConsecutiveComments 設定為 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

為單行和區塊註解使用不同選項

如果您希望單行註解和區塊註解具有不同的設定，您可以使用兩種不同的物件設定來實現（請注意，大小寫選項將針對單行和區塊註解強制執行一致性）

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

使用不同單行和區塊註解設定的錯誤程式碼範例

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

使用不同單行和區塊註解設定的正確程式碼範例

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

資源

• 規則來源
• 測試來源