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

Зачем нужны комментарии в коде?

Комментарии в коде – это пояснительные записки для программистов (и для вас в будущем), которые объясняют, что делает код и почему он это делает. Они игнорируются интерпретатором и не влияют на выполнение программы. Комментарии помогают понять сложную логику, облегчают отладку и упрощают совместную разработку.

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

Хорошо прокомментированный код – это самодокументирующийся код. Он значительно упрощает понимание логики даже спустя месяцы или годы после написания. Комментарии критически важны при поддержке и модификации кода, особенно если над ним работает несколько разработчиков. Без комментариев код может превратиться в трудноподдерживаемый «спагетти-код».

Краткий обзор синтаксиса комментариев в Google Apps Script

В Google Apps Script, как и в большинстве языков программирования, используются два основных типа комментариев:

Однострочные комментарии: Начинаются с // и распространяются до конца строки.

Многострочные комментарии: Заключаются между /* и */ и могут охватывать несколько строк.

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

Синтаксис однострочных комментариев (//)

Однострочные комментарии начинаются с двойного слеша (//). Все, что находится после // до конца строки, считается комментарием и игнорируется интерпретатором.

// Это однострочный комментарий
let clicks: number = 0; // Инициализация счетчика кликов

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

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

let campaignName: string = "Autumn Sale"; // Название рекламной кампании
if (clicks > 1000) { // Проверяем, превысило ли количество кликов 1000
  Logger.log("Кампания " + campaignName + " успешна!"); // Выводим сообщение в лог
}

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

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

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

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

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

Синтаксис многострочных комментариев (/* … */)

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

/*
  Это многострочный комментарий.
  Он может занимать несколько строк.
  И использоваться для более подробного объяснения кода.
*/
function calculateCTR(clicks: number, impressions: number): number {
  /*
    Функция calculateCTR вычисляет CTR (Click-Through Rate) для рекламной кампании.
    CTR = (Количество кликов / Количество показов) * 100
  */
  if (impressions === 0) {
    return 0; // Чтобы избежать деления на ноль
  }
  return (clicks / impressions) * 100;
}

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

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

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

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

Многострочные комментарии для временного отключения блоков кода (commenting out)

Многострочные комментарии часто используются для временного отключения блоков кода во время отладки или экспериментов. Это позволяет легко исключить код из выполнения, не удаляя его.

/*
  let oldCode = "что то старое";
  Logger.log(oldCode);
*/

Лучшие практики комментирования в Google Apps Script

Что следует комментировать: переменные, функции, логику

Переменные: Комментируйте переменные, если их назначение или тип данных не очевидны из имени.

Функции: Обязательно комментируйте функции, объясняя их назначение, параметры и возвращаемые значения.

Логику: Комментируйте сложные или неочевидные фрагменты кода, объясняя логику их работы.

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

Пишите комментарии на понятном и доступном языке.

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

Избегайте грамматических ошибок и опечаток.

Поддерживайте актуальность комментариев при изменении кода.

Использование комментариев для создания документации (JSDoc-подобные комментарии)

Хотя Google Apps Script не поддерживает JSDoc напрямую, можно использовать JSDoc-подобные комментарии для документирования функций и классов. Это позволяет генерировать документацию автоматически с помощью сторонних инструментов.

/**
 * @param {number} clicks Количество кликов.
 * @param {number} impressions Количество показов.
 * @return {number} CTR (Click-Through Rate).
 */
function calculateCTR(clicks: number, impressions: number): number {
  if (impressions === 0) {
    return 0; // Чтобы избежать деления на ноль
  }
  return (clicks / impressions) * 100;
}

Избегайте избыточного комментирования

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

Примеры продвинутого комментирования и отладки

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

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

function processData(data: any[]) {
  // Logger.log("Данные для обработки: " + JSON.stringify(data)); // Отладочный вывод данных
  for (let i = 0; i < data.length; i++) {
    //if (data[i].isValid) { // Временно отключаем проверку валидности
      // ...
    //} 
  }
}

Создание TODO комментариев для будущих задач

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

function processData(data: any[]) {
  // TODO: Добавить проверку на наличие обязательных полей
  for (let i = 0; i < data.length; i++) {
    // ...
  }
}

Интеграция комментариев с системами контроля версий (например, Git)

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