Документирование правила

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

Качественная документация выполняет несколько задач:

  • объясняет проблему, которую решает правило;
  • показывает корректные и некорректные примеры кода;
  • описывает доступные параметры конфигурации;
  • упрощает внедрение правила в проект;
  • снижает количество ошибок при использовании;
  • помогает сопровождать правило в будущем.

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

Стандартная структура документации

Большинство ESLint-проектов придерживаются единого формата описания правил. Обычно для каждого правила создаётся отдельный Markdown-файл.

Пример структуры:

docs/
└── rules/
    └── no-console-log.md

Типичная документация содержит следующие разделы:

  1. Название правила.
  2. Описание проблемы.
  3. Причины использования.
  4. Некорректные примеры.
  5. Корректные примеры.
  6. Параметры конфигурации.
  7. Когда использовать правило.
  8. Когда не использовать правило.
  9. Связанные правила.

Заголовок правила

Документация обычно начинается с названия правила.

Пример:

# no-console-log

Сразу после заголовка размещается краткое описание.

# no-console-log

Запрещает использование console.log в производственном коде.

Описание должно быть коротким и максимально конкретным.

Нежелательный вариант:

Правило проверяет некоторые случаи использования консоли.

Предпочтительный вариант:

Запрещает вызовы console.log, поскольку отладочные сообщения
не должны попадать в production-сборку.

Объяснение проблемы

После краткого описания раскрывается причина существования правила.

Пример:

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

В этом разделе полезно описывать:

  • потенциальные ошибки;
  • проблемы поддержки;
  • риски производительности;
  • нарушения архитектурных соглашений;
  • требования кодстайла команды.

Документация должна объяснять не только что запрещается, но и почему это запрещается.

Раздел «Некорректный код»

Почти каждая официальная документация ESLint содержит блоки с примерами нарушений.

Традиционно используется подпись:

## Examples of incorrect code for this rule:

Пример:

## Examples of incorrect code for this rule:

```js
console.log("debug");
```

```js
console.log(user);
```

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

## Некорректный код

```js
console.log("test");
```

```js
console.log(response);
```

Примеры должны быть минимальными и демонстрировать только нарушение конкретного правила.

Плохо:

function processData(data) {
  const result = transform(data);

  console.log(result);

  return result;
}

Лучше:

console.log(result);

Раздел «Корректный код»

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

Пример:

## Корректный код

```js
logger.info(result);
```

```js
sendMetric(result);
```

Такой подход помогает понять ожидаемый стиль программирования.

Если правило запрещает конструкцию без альтернативы, всё равно полезно показать допустимый вариант.

Например:

Нарушение:

var count = 0;

Исправление:

let count = 0;

Документирование параметров правила

Многие правила ESLint поддерживают настройки через объект конфигурации.

Пример конфигурации:

{
  "rules": {
    "custom/max-function-size": [
      "error",
      {
        "maxLines": 50
      }
    ]
  }
}

Каждый параметр необходимо описывать отдельно.

Пример:

### maxLines

Тип: number

Значение по умолчанию: 50

Определяет максимально допустимое количество строк
внутри функции.

Для нескольких параметров рекомендуется использовать таблицу.

| Параметр | Тип | По умолчанию | Описание |
|-----------|------|--------------|-----------|
| maxLines | number | 50 | Максимальное число строк |
| ignoreComments | boolean | false | Игнорировать комментарии |

Описание схемы настроек

Если правило использует JSON Schema для валидации опций, документация должна отражать ограничения этой схемы.

Пример схемы:

schema: [
  {
    type: "object",
    properties: {
      allowWarn: {
        type: "boolean"
      }
    },
    additionalProperties: false
  }
]

Соответствующее описание:

### allowWarn

Разрешает использование console.warn.

Допустимые значения:

- true
- false

Важно явно указывать:

  • допустимые типы;
  • диапазоны значений;
  • возможные комбинации параметров;
  • значения по умолчанию.

Документирование вариантов поведения

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

Например:

Конфигурация:

{
  "custom/no-console-log": [
    "error",
    {
      "allowWarn": true
    }
  ]
}

Некорректный код:

console.log("message");

Корректный код:

console.warn("warning");

Для другой конфигурации:

{
  "custom/no-console-log": [
    "error",
    {
      "allowWarn": false
    }
  ]
}

Некорректным станет уже следующий код:

console.warn("warning");

Документация должна отражать все значимые сценарии использования.

Документирование автоматически исправляемых правил

Если правило поддерживает автоматическое исправление, это следует указывать явно.

В метаданных правило содержит:

meta: {
  fixable: "code"
}

Документация может содержать отдельный раздел.

## Автоматическое исправление

Правило поддерживает автоматическое исправление через ESLint.

До исправления:

```js
var count = 0;
```

После исправления:

```js
let count = 0;
```

Также полезно указать команду запуска:

eslint . --fix

Документирование предложений исправления

Начиная с ESLint 7 появилась возможность предоставлять suggestions.

Пример метаданных:

meta: {
  hasSuggestions: true
}

Если правило использует подсказки, их желательно перечислять.

Пример:

Возможные предложения исправления:

- заменить var на let;
- заменить var на const.

Это особенно полезно для пользователей редакторов, поддерживающих ESLint Suggestions.

Указание ограничений правила

Любое правило имеет границы применимости.

Пример:

Ограничения:

- анализируются только прямые вызовы console.log;
- динамические обращения через переменные не проверяются;
- обращения через globalThis не обрабатываются.

Подобная информация предотвращает ложные ожидания пользователей.

Раздел «Когда использовать правило»

Этот раздел помогает принять решение о включении правила в проект.

Пример:

Используйте правило, если:

- требуется строгий контроль качества кода;
- запрещены отладочные сообщения;
- проект имеет production-ориентированные стандарты.

Особенно полезен для больших наборов правил, где не каждое правило подходит всем проектам.

Раздел «Когда не использовать правило»

Не менее важен и обратный сценарий.

Пример:

Не используйте правило, если:

- проект находится на стадии прототипирования;
- console.log является частью процесса диагностики;
- команда не ограничивает использование консольного вывода.

Такие рекомендации помогают избежать чрезмерного применения линтеров.

Документирование взаимодействия с другими правилами

Некоторые правила пересекаются между собой.

Например:

Связанные правила:

- no-console
- no-debugger
- custom/no-console-log

Если правило дублирует функциональность другого правила или расширяет её, это следует указывать напрямую.

Пример:

Данное правило является более строгой альтернативой no-console,
поскольку запрещает только console.log и позволяет использовать
остальные методы объекта console.

Документирование причин исключений

Иногда правило содержит специальные исключения.

Пример реализации:

if (node.parent.type === "CatchClause") {
  return;
}

Документация должна объяснять подобное поведение.

Пример:

Внутри блоков catch использование console.error допускается,
поскольку оно применяется для регистрации ошибок.

Любое нестандартное решение в коде правила желательно отражать в документации.

Использование Markdown для оформления

Документация правил ESLint чаще всего хранится в формате Markdown.

Основные элементы оформления:

Заголовки:

# Заголовок первого уровня
## Заголовок второго уровня
### Заголовок третьего уровня

Списки:

- Пункт 1
- Пункт 2
- Пункт 3

Нумерация:

1. Первый пункт
2. Второй пункт
3. Третий пункт

Таблицы:

| Опция | Тип |
|--------|------|
| allow | boolean |

Блоки кода:

```js
const value = 1;
```

Единый стиль оформления облегчает навигацию по документации всего набора правил.

Синхронизация документации и реализации

Наиболее распространённая проблема — устаревшая документация.

Типичные ситуации:

  • добавлена новая опция, но описание не обновлено;
  • изменено значение по умолчанию;
  • появились новые исключения;
  • изменились примеры кода.

Для предотвращения расхождений часто используется следующий процесс:

  1. Изменение правила.
  2. Обновление тестов.
  3. Обновление документации.
  4. Проверка примеров перед публикацией.

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

Типичный шаблон документации правила

# custom-rule

Краткое описание назначения правила.

## Почему существует это правило

Описание проблемы и мотивации.

## Некорректный код

```js
// пример нарушения
```

## Корректный код

```js
// корректный пример
```

## Опции

### optionA

Описание параметра.

### optionB

Описание параметра.

## Автоматическое исправление

Описание поведения fix.

## Ограничения

Описание известных ограничений.

## Когда использовать правило

Рекомендации по применению.

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

Сценарии, в которых правило не требуется.

## Связанные правила

- another-rule
- some-other-rule

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

Оглавление