no-warning-comments

Запрещает указанные предупреждающие термины в комментариях

Разработчики часто добавляют комментарии к незавершённому коду или коду, требующему проверки. Скорее всего, вы захотите исправить или проверить код, а затем удалить комментарий, прежде чем считать код готовым к использованию в рабочей среде.

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

Подробности правила

Это правило сообщает о комментариях, содержащих любой из предопределённых терминов, указанных в конфигурации.

Параметры

Это правило принимает объект с параметрами:

• "terms": необязательный массив терминов для поиска. По умолчанию используется ["todo", "fixme", "xxx"]. Регистр символов в терминах не учитывается, поиск выполняется по целым словам: fix совпадёт с FIX, но не с fixing. Термины могут состоять из нескольких слов: really bad idea.
• "location": необязательная строка, задающая, в какой части комментариев искать совпадения. По умолчанию используется "start". Поиск начинается с первого недекоративного символа; пробелы, символы новой строки и символы, указанные в decoration, игнорируются. Другое значение — поиск anywhere в комментариях.
• "decoration": необязательный массив символов, игнорируемых в начале комментария, если для параметра location задано значение "start". По умолчанию используется []. Любая последовательность пробельных символов или символов из этого свойства игнорируется. Этот параметр игнорируется, если для location задано значение "anywhere".

Пример неправильного кода для параметров { "terms": ["todo", "fixme", "xxx"], "location": "start" } по умолчанию:

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

/*FIXME*/
function callback(err, results) {
  if (err) {
    console.error(err);
    return;
  }
  // TODO
}

Пример правильного кода для параметров { "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
}

термины и расположение

Примеры неправильного кода для параметров { "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 */

Примеры правильного кода для параметров { "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
 */

Декоративные символы

Примеры неправильного кода для параметров { "decoration": ["*"] }:

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

//***** todo decorative asterisks are ignored *****//
/** * TODO new lines and asterisks are also ignored in block comments. */

Примеры неправильного кода для параметров { "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. */

Примеры правильного кода для параметров { "decoration": ["/", "*"] }:

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

//!TODO preceded by non-decoration character
/**
 *!TODO preceded by non-decoration character in a block comment
 */

Когда не следует использовать это правило

• Если у вас большая кодовая база, разработанная без политики, запрещающей использование таких предупреждающих терминов, вы можете получить сотни предупреждений и ошибок. Это может оказаться контрпродуктивным, если вы не сможете исправить их все (например, если у вас не будет на это времени): вы можете пропустить другие предупреждения и ошибки или привыкнуть к их большому количеству и перестать обращать на них внимание.
• По той же причине, что и выше: не следует настраивать термины, которые используются очень часто (например, ключевые слова родного языка, используемые в комментариях).

Версия

Это правило добавлено в ESLint v0.4.4.

Ресурсы

• Исходный код правила
• Исходный код тестов