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

/* istanbul ignore next */
/* jscs:enable */
/* jshint asi:true */
/* global foo */
/* globals foo */
/* exported myVar */
// https://github.com

/* eslint semi:2 */
/* eslint-disable */
foo
/* eslint-enable */
// eslint-disable-next-line
baz
bar // eslint-disable-line

Параметры

У этого правила есть два параметра: строковое значение "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

/* istanbul ignore next */
/* jscs:enable */
/* jshint asi:true */
/* global foo */
/* globals foo */
/* exported myVar */
// https://github.com

/* eslint semi:2 */
/* eslint-disable */
foo
/* eslint-enable */
// eslint-disable-next-line
baz
bar // eslint-disable-line

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

Ресурсы

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