Стили комментирования кода

Комментарии в коде играют важную роль в его поддерживаемости, понятности и удобстве работы команды разработчиков. В рамках тестирования с использованием WebdriverIO комментарии помогают не только понять логику тестов, но и обеспечить их масштабируемость и удобство для других участников проекта.

Виды комментариев

В языке JavaScript существуют два основных способа комментирования кода:

  1. Однострочные комментарии. Такие комментарии начинаются с двойного слэша // и продолжаются до конца строки. Это удобный способ кратко пояснить часть кода, особенно для простых выражений или операций.

    Пример:

    // Устанавливаем timeout для теста
browser.setTimeout({ 'pageLoad': 5000 });

  2. Многострочные комментарии. Начинаются с /* и заканчиваются на */. Они используются для более длинных пояснений или временного исключения больших блоков кода.

    Пример:

    /*
  Параметры конфигурации для теста
  Включают:
    - URL страницы
    - Timeout на ожидание элементов
    - Параметры для браузера
*/
const config = {
  baseUrl: 'https://example.com',
  waitForTimeout: 3000
};

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

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

    Пример:

    // Неправильно: код самоочевиден
let a = 5; // Присваиваем переменной a значение 5

  2. Использовать комментарии для объяснения логики теста. В тестах важно описывать, что именно проверяется, а не только что делает код. Тестирование должно быть понятно как для текущих, так и для будущих разработчиков.

    Пример:

    // Проверяем, что кнопка отправки формы активна после ввода данных
it('should enable submit button after entering name', () => {
  $('#name').setValue('John Doe');
  expect($('#submit').isEnabled()).toBe(true);
});

  3. Не использовать комментарии для временного исключения кода. Если код необходимо временно исключить, лучше воспользоваться механизмами системы контроля версий (например, git), чем оставлять «закомментированный» код.

  4. Использовать комментарии для указания на “TODO” или будущие улучшения. В проектах, где тесты развиваются и изменяются, важно использовать комментарии для пометок по улучшению кода или выполнению задач в будущем.

    Пример:

    // TODO: Добавить проверку валидности email
it('should submit the form correctly', () => {
  $('#email').setValue('john.doe@example.com');
  $('#submit').click();
  // Проверить успешное сообщение
});

Структура комментариев

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

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

    Пример:

    // Тестирование процесса регистрации нового пользователя
it('should allow a new user to register', () => {
  $('#username').setValue('new_user');
  $('#password').setValue('password123');
  $('#submit').click();
  expect($('#confirmation')).toBeVisible();
});

  2. Комментарии в сложных участках кода. Если часть теста сложна для понимания, желательно подробно объяснить, что происходит на каждом шаге, почему выбран именно такой подход и какие могут быть потенциальные риски.

    Пример:

    // Используем delay перед кликом, чтобы дождаться полной загрузки страницы
browser.pause(1000);
$('#submit').click();

  3. Разделение логических блоков. В больших тестах можно разделить код на логические блоки и снабдить их комментариями, объясняющими назначение каждого блока.

    Пример:

    // 1. Ожидание загрузки страницы
browser.waitUntil(() => {
  return $('#main').isDisplayed();
}, 5000, 'Page did not load in time');

// 2. Заполнение формы
$('#username').setValue('user1');
$('#email').setValue('user1@example.com');

Стандарты для комментариев

  1. Ясность и краткость. Комментарии должны быть ясными и лаконичными. Излишне длинные комментарии только усложняют восприятие кода.

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

  3. Форматирование комментариев. Для повышения читаемости больших блоков комментариев можно использовать форматирование. Например, выделение заголовков и подзаголовков помогает разделить текст на логические части и делает его легче воспринимаемым.

    Пример:

    // ==============================
// Проверка авторизации пользователя
// ==============================
it('should login with valid credentials', () => {
  $('#username').setValue('validUser');
  $('#password').setValue('validPassword');
  $('#submit').click();
  expect($('#dashboard')).toBeVisible();
});

Инструменты для автоматизации

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

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

Комментарии в асинхронных тестах

Особое внимание стоит уделить комментариям в асинхронных тестах. Когда тесты используют такие методы как browser.pause(), browser.waitUntil(), или промисы, важно четко указать, что происходит на каждом шаге, чтобы избежать недоразумений.

Пример:

// Ожидаем, пока элемент не станет видимым
browser.waitUntil(() => {
  return $('#element').isDisplayed();
}, 5000, 'Element was not visible in time');

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

Заключение

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

Оглавление