capitalized-comments

Принудительное или запрещение прописных букв в первом слове комментария

Комментарии полезны для передачи информации будущим разработчикам. Чтобы эта информация была полезной и не отвлекала внимание, иногда желательно, чтобы комментарии следовали определённому стилю. Одним из элементов стилей форматирования комментариев является то, следует ли писать первое слово комментария с заглавной или строчной буквы.

В целом, ни один стиль комментариев не является более или менее допустимым, чем другие, но многие разработчики согласятся, что согласованный стиль может повысить поддерживаемость проекта.

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

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

По умолчанию это правило требует использования буквы, отличной от строчной, в начале комментария.

Примеры неправильного кода для этого правила:

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

// lowercase comment

Примеры правильного кода для этого правила:

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

Параметры

Это правило имеет два параметра: строковое значение "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-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 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.
 */

Примеры неправильного кода с 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.

Использование разных параметров для строчных и блочных комментариев

Если вы хотите использовать разные настройки для строчных и блочных комментариев, вы можете использовать две разные конфигурации объектов (обратите внимание, что параметр с прописными буквами будет применяться последовательно для строчных и блочных комментариев):

{
    "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
• JSCS: disallowCapitalizedComments

Версия

Это правило было введено в ESLint v3.11.0.

Ресурсы

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