Каждое правило ESLint сопровождается собственной страницей документации. Такая страница содержит описание поведения правила, примеры корректного и некорректного кода, сведения о доступных параметрах настройки и дополнительную информацию о том, когда применение правила оправдано или, наоборот, нежелательно.
Умение читать документацию по правилу позволяет быстро определить:
--fix.Большинство страниц правил ESLint имеют схожую структуру, поэтому после освоения общего подхода работа с документацией становится значительно проще.
В верхней части страницы обычно располагается название правила и краткое пояснение его назначения.
Например:
eqeqeq
Require the use of === and !==Из названия не всегда понятно поведение правила, поэтому ключевую информацию содержит именно описание.
В приведённом примере становится ясно, что правило требует использования строгого сравнения:
a === b
a !== bвместо:
a == b
a != bКраткое описание помогает быстро определить, относится ли правило к текущей задаче.
При чтении документации важно определить, какой тип задачи решает правило.
Условно правила можно разделить на несколько групп.
Такие правила помогают находить потенциальные дефекты программы.
Пример:
if (value = 10) {
}Здесь вместо сравнения случайно выполнено присваивание.
Правило:
no-cond-assignобнаруживает подобные ситуации.
Подобные правила обычно рекомендуется включать практически во всех проектах.
Некоторые правила не предотвращают ошибки напрямую, а делают код более понятным.
Например:
curlyтребует использование фигурных скобок.
Без скобок:
if (ready)
start();Со скобками:
if (ready) {
start();
}Часть правил отвечает исключительно за стиль.
Например:
quotessemicomma-dangleОни позволяют поддерживать единообразный внешний вид кода.
Практически каждая страница содержит раздел:
Rule DetailsЭто основной блок документации.
В нём подробно объясняется логика работы правила и приводятся примеры.
Именно с этого раздела обычно начинается детальное изучение правила.
Обычно после описания располагается раздел вида:
Examples of incorrect code for this rule:или
The following code is considered incorrect:Здесь показаны конструкции, которые ESLint будет считать нарушением.
Например, для правила eqeqeq:
if (a == b) {
}if (a != b) {
}При чтении данного блока важно определить:
Например, после анализа примеров можно сделать вывод, что правило запрещает нестрогое сравнение.
Следующий важный раздел:
Examples of correct code for this rule:или
The following code is considered correct:Здесь демонстрируются допустимые варианты.
Для eqeqeq:
if (a === b) {
}if (a !== b) {
}Этот блок особенно полезен при миграции существующего проекта.
Некоторые правила имеют сложную логику, и только по корректным примерам становится понятно, как именно должен выглядеть код после исправления.
Наиболее эффективный способ чтения документации — сравнивать оба набора примеров одновременно.
Некорректный вариант:
foo == nullКорректный вариант:
foo === nullТакое сравнение позволяет быстро увидеть различия.
Если правило сложное, полезно выписать:
| Некорректно | Корректно |
|---|---|
== |
=== |
!= |
!== |
Для правил с большим количеством вариантов это существенно ускоряет понимание.
Многие правила поддерживают параметры конфигурации.
В документации этот раздел обычно называется:
Optionsили
Options for this ruleЗдесь перечисляются все допустимые настройки.
Например:
{
"eqeqeq": ["error", "always"]
}или
{
"eqeqeq": ["error", "smart"]
}Из документации можно узнать:
Особое внимание следует уделять настройке по умолчанию.
Например, правило может поддерживать пять различных режимов, однако без дополнительной конфигурации использовать только один из них.
Пример:
{
"rule-name": "error"
}и
{
"rule-name": ["error", "strict"]
}могут давать разные результаты.
Если значение по умолчанию не изучено, существует риск неправильной интерпретации работы правила.
Хорошая документация ESLint показывает примеры отдельно для каждого режима настройки.
Например:
{
"quotes": ["error", "single"]
}Некорректно:
const name = "Alex";Корректно:
const name = 'Alex';Другой режим:
{
"quotes": ["error", "double"]
}Теперь ситуация меняется на противоположную.
Поэтому недостаточно прочитать только список параметров — необходимо изучить примеры их использования.
Некоторые страницы содержат пометки:
Fixableили
Automatically fixableЭто означает, что правило поддерживает автоматическое исправление.
Например:
const x = "test";может быть автоматически преобразовано в:
const x = 'test';при запуске:
eslint . --fixНаличие автоматического исправления особенно важно при подключении нового правила в крупном проекте.
Иногда в документации присутствует пометка:
Has SuggestionsЭто означает, что правило способно предлагать варианты исправления через редактор кода.
Например, VS Code может показать действие:
Quick Fixи предложить один или несколько вариантов изменения программы.
Следует понимать разницу:
Очень важный, но часто игнорируемый раздел:
When Not To Use ItЗдесь описываются ситуации, когда правило может оказаться избыточным.
Например:
Если документация содержит такой раздел, его необходимо читать полностью.
Иногда именно он помогает понять, почему правило отсутствует в популярных конфигурациях.
Не каждое правило способно анализировать код идеально.
В документации могут быть указаны ограничения:
Known Limitationsили пояснения внутри основного текста.
Например:
Подобные ограничения позволяют избежать ложных ожиданий от линтера.
Многие страницы содержат информацию о том, в какой версии ESLint появилось правило.
Пример:
Introduced in ESLint v8.10.0или аналогичная запись.
Это полезно при сопровождении старых проектов.
Если правило отсутствует в текущей версии ESLint, необходимо проверить историю его появления.
Также некоторые правила получают новые параметры в более поздних релизах.
Документация обычно показывает реальные варианты настройки.
Например:
{
"rules": {
"eqeqeq": "error"
}
}или:
export default [
{
rules: {
eqeqeq: "error"
}
}
];Важно определить:
.eslintrc;Это особенно актуально для современных версий ESLint.
Хотя документация правила обычно сосредоточена на поведении, полезно помнить о возможных уровнях серьёзности:
"off""warn""error"Пример:
{
"eqeqeq": "warn"
}или:
{
"eqeqeq": "error"
}Само правило остаётся одинаковым, однако реакция линтера различается.
Во многих случаях документация упоминает другие правила.
Например:
See alsoили ссылки внутри описания.
Причина заключается в том, что некоторые правила решают близкие задачи.
Например:
eqeqeqчасто рассматривается вместе с:
no-eq-nullИзучение связанных правил помогает сформировать целостное понимание набора проверок.
При изучении любого правила удобно придерживаться следующего порядка:
Прочитать краткое описание.
Определить тип правила:
Изучить раздел Rule Details.
Просмотреть все некорректные примеры.
Просмотреть все корректные примеры.
Сравнить обе группы примеров.
Изучить раздел Options.
Проверить значения по умолчанию.
Определить наличие Fixable.
Проверить наличие Suggestions.
Прочитать раздел When Not To Use It.
Ознакомиться с ограничениями и особенностями реализации.
Такой подход позволяет быстро понять назначение правила, корректно настроить его в проекте и избежать распространённых ошибок при интерпретации документации ESLint.