Как вставить комментарий в Google Apps Script: полное руководство

Что такое комментарии и зачем они нужны?

Комментарии в Google Apps Script (GAS) — это пояснительные заметки, которые разработчики вставляют в код для объяснения его логики, назначения или особенностей. Они не выполняются интерпретатором и игнорируются при выполнении скрипта. Комментарии служат своего рода «внутренней документацией» для программистов.

Важность комментирования кода для читаемости и поддержки

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

Сложная логика: Объяснение алгоритмов, нетривиальных решений.

Совместная работа: Понимание кода другими разработчиками.

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

Долгосрочное использование: Вспомнить логику кода спустя время.

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

Обзор различных типов комментариев в Google Apps Script

В Google Apps Script, как и в JavaScript, поддерживаются два типа комментариев:

Однострочные комментарии: Используются для кратких пояснений на одной строке.

Многострочные комментарии: Используются для более подробных объяснений, охватывающих несколько строк.

Однострочные комментарии в Google Apps Script

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

Чтобы добавить однострочный комментарий, используйте два слеша //. Все, что находится после // на этой строке, будет игнорироваться интерпретатором.

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

function calculateCTR(clicks: number, impressions: number): number {
  // Проверяем, что количество показов не равно нулю, чтобы избежать деления на ноль
  if (impressions === 0) {
    return 0; // Если показов нет, CTR равен 0
  }

  let ctr: number = clicks / impressions; // Вычисляем CTR
  return ctr;  // Возвращаем значение CTR
}

Советы по эффективному использованию однострочных комментариев

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

Размещайте комментарии непосредственно перед кодом, который они объясняют.

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

Многострочные комментарии в Google Apps Script

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

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

Примеры использования многострочных комментариев

/**
 * Функция для получения статистики рекламной кампании.
 *
 * @param {string} campaignName Название рекламной кампании.
 * @return {Object} Объект, содержащий статистику кампании (показы, клики, CTR).
 */
function getCampaignStats(campaignName: string): object {
  // Логика получения статистики.
  let stats: object = { /* ... */ };
  return stats;
}

Когда использовать многострочные комментарии вместо однострочных

Для подробного описания функций, классов или блоков кода.

Для документирования параметров и возвращаемых значений функций (как в примере выше).

Для временного отключения больших фрагментов кода во время отладки.

Рекомендации по написанию комментариев в Google Apps Script

Содержание комментариев: что комментировать?

Неочевидная логика: Объясните, почему код работает именно так.

Сложные алгоритмы: Опишите шаги алгоритма.

Необычные решения: Объясните, почему было выбрано именно это решение.

API и библиотеки: Опишите, как использовать API или библиотеки.

Предположения и ограничения: Укажите известные ограничения или предположения.

Стиль комментариев: как писать понятные и лаконичные комментарии

Пишите четким и понятным языком.

Избегайте жаргона и аббревиатур, если они не общеизвестны.

Будьте краткими и лаконичными, но не жертвуйте ясностью.

Обновляйте комментарии при изменении кода.

Использование комментариев для документирования функций и скриптов

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

Укажите, что функция делает, какие параметры она принимает и что возвращает.

Используйте аннотации JSDoc (например, @param, @return) для автоматической генерации документации.

Примеры хороших и плохих комментариев

Плохой комментарий:

let x = 5; // Присваиваем 5 переменной x

Хороший комментарий:

// Устанавливаем лимит показов по умолчанию в 5, чтобы избежать перерасхода бюджета
let x = 5;

Плохой комментарий:

function foo() {
  // Делаем что-то
}

Хороший комментарий:

/**
 * Функция для оптимизации ставок в Google Ads на основе данных о конверсиях.
 */
function optimizeBids() {
  // Логика оптимизации ставок.
}

Продвинутые техники комментирования

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

Временно отключайте фрагменты кода, закомментировав их.

Используйте console.log() внутри комментариев для вывода значений переменных.

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

Комментарии как часть процесса разработки и код-ревью

Требуйте комментирования кода в рамках код-ревью.

Обращайте внимание на качество и полноту комментариев.

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

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

Существуют инструменты, которые позволяют автоматически генерировать документацию из комментариев в коде (например, JSDoc).

Это упрощает создание и поддержание актуальной документации.