no-warning-comments

禁止在註解中出現指定的警告詞彙

開發人員經常在程式碼中新增註解，標示未完成或需要審查的部分。最有可能的情況是，您希望在認為程式碼可以正式發佈之前，先修正或審查程式碼，然後移除註解。

// TODO: do something
// FIXME: this is not a good idea
1
2

規則詳細資訊

此規則會回報包含在其設定中指定的任何預定義詞彙的註解。

選項

此規則具有選項物件字面值

• "terms"：可選的詞彙陣列，用於比對。預設值為 ["todo", "fixme", "xxx"]。詞彙比對不區分大小寫，且為完整單字：fix 會比對到 FIX，但不會比對到 fixing。詞彙可以包含多個單字：really bad idea。
• "location"：可選的字串，設定在註解中的哪個位置檢查比對。預設值為 "start"。起始位置是從第一個非裝飾字元開始，忽略空白字元、換行符號和 decoration 中指定的字元。另一個值是比對註解中的anywhere（任何位置）。
• "decoration"：可選的字元陣列，當位置為 "start" 時，在註解開頭會被忽略。預設值為 []。任何空白字元序列或此屬性中的字元都會被忽略。當位置為 "anywhere" 時，此選項會被忽略。

針對預設選項 { "terms": ["todo", "fixme", "xxx"], "location": "start" } 的錯誤程式碼範例

/*eslint no-warning-comments: "error"*/

/*
FIXME
*/
function callback(err, results) {
  if (err) {
    console.error(err);
    return;
  }
  // TODO
}
1
2
3
4
5
6
7
8
9
10
11
12

針對預設選項 { "terms": ["todo", "fixme", "xxx"], "location": "start" } 的正確程式碼範例

/*eslint no-warning-comments: "error"*/

function callback(err, results) {
  if (err) {
    console.error(err);
    return;
  }
  // NOT READY FOR PRIME TIME
  // but too bad, it is not a predefined warning term
}
1
2
3
4
5
6
7
8
9
10

詞彙和位置

針對選項 { "terms": ["todo", "fixme", "any other term"], "location": "anywhere" } 的錯誤程式碼範例

/*eslint no-warning-comments: ["error", { "terms": ["todo", "fixme", "any other term"], "location": "anywhere" }]*/

// TODO: this
// todo: this too
// Even this: TODO
/*
 * The same goes for this TODO comment
 * Or a fixme
 * as well as any other term
 */
1
2
3
4
5
6
7
8
9
10

針對選項 { "terms": ["todo", "fixme", "any other term"], "location": "anywhere" } 的正確程式碼範例

/*eslint no-warning-comments: ["error", { "terms": ["todo", "fixme", "any other term"], "location": "anywhere" }]*/

// This is to do
// even not any other    term
// any other terminal
/*
 * The same goes for block comments
 * with any other interesting term
 * or fix me this
 */
1
2
3
4
5
6
7
8
9
10

裝飾字元

針對選項 { "decoration": ["*"] } 的錯誤程式碼範例

/*eslint no-warning-comments: ["error", { "decoration": ["*"] }]*/

//***** todo decorative asterisks are ignored *****//
/**
 * TODO new lines and asterisks are also ignored in block comments.
 */
1
2
3
4
5
6

針對選項 { "decoration": ["/", "*"] } 的錯誤程式碼範例

/*eslint no-warning-comments: ["error", { "decoration": ["/", "*"] }]*/

////// TODO decorative slashes and whitespace are ignored //////
//***** todo decorative asterisks are also ignored *****//
/**
 * TODO new lines are also ignored in block comments.
 */
1
2
3
4
5
6
7

針對選項 { "decoration": ["/", "*"] } 的正確程式碼範例

/*eslint no-warning-comments: ["error", { "decoration": ["/", "*"] }]*/

//!TODO preceded by non-decoration character
/**
 *!TODO preceded by non-decoration character in a block comment
 */
1
2
3
4
5
6

何時不該使用

• 如果您有大量程式碼庫，且開發時沒有禁止使用此類警告詞彙的政策，您可能會收到數百個警告/錯誤，如果您無法修正所有這些問題（例如，如果您沒有時間這樣做），這可能會適得其反，因為您可能會忽略其他警告/錯誤，或者習慣於許多警告/錯誤而不再關注它們。
• 與上述觀點相同的原因：您不應設定非常常用的詞彙（例如，註解中使用的母語的核心部分）。

版本

此規則於 ESLint v0.4.4 版本中引入。

資源

• 規則來源
• 測試來源