Зачем комментировать исходный код и как это делать правильно

Документирующие и поясняющие комментарии

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

• Поясняющие логику кода, использование алгоритмов. Разработчики применяют их на своё усмотрение.
• Документирующие — обязательные комментарии, содержащие информацию о назначении объектов, входных и выходных параметрах (если они есть), данные о разработчике и других важных вещах, относящихся к фрагменту кода. Они располагаются в заголовках модулей, библиотек, процедур и функций.

Пример на языке Java:

/**
 Класс-коннектор для обеспечения взаимодействия с сервером
* Подключается через {@link Socket}
* посылает GET-запрос
* использует {@link ObjectInputStream} и {@link ObjectOutputStream}.
*/
public class ServerConnector

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

Как комментируют функции и библиотеки

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

Например, документирующий комментарий из заголовка библиотеки Lodash для JavaScript выглядит так:

/**
 * @license
 * Lodash 
 * Copyright OpenJS Foundation and other contributors 
 * Released under MIT license 
 * Based on Underscore.js 1.8.3 
 * Copyright Jeremy Ashkenas, DocumentCloud and Investigative Reporters & Editors
 */

Кроме этого, в заголовочных комментариях к функциям указывают стандартный набор сведений:

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

Пример из той же библиотеки Lodash:

/**
   * Добавляет элементы `values` в `array`.
   *
   * @private
   * @param {Array} array Массив для изменения.
   * @param {Array} values Значения для добавления.
   * @returns {Array} Возвращает обработанный массив
   */
  function arrayPush(array, values) {
	var index = -1,
    	length = values.length,
    	offset = array.length;
 
	while (++index < length) {
      array[offset + index] = values[index];
	}
	return array;
  }

Главное здесь — избегать бессмысленных комментариев. Вот пример плохого описания процедуры на языке 1С:

// Процедура запускает обработку очереди заданий.
//
// Параметры:
//	Настройки – Структура – настройки процедуры
 Процедура ЗапуститьОбработкуОчередиЗаданий (Настройки, БыстрыйРежим = Ложь)

Как автоматизировать создание комментариев

В различных IDE есть возможность автоматизировать создание комментариев. Это делается с использованием тегов — дескрипторов, которые начинаются с символа @. Вот самые популярные:

• @author — идентифицирует автора исходного кода;
• @param — определяет параметр метода;
• @see — ссылка;
• @since — версия программного обеспечения;
• @return — тип возвращаемых процедурой или функцией данных.

Из таких комментариев автоматически формируется документация программы. Для этого используют генераторы документации, например, javadoc для языка Java, phpDocumentor для PHP, doxygen для C и C++, Epydoc для Pithon и другие.

Принцип работы прост. Генератор обрабатывает файл с исходным текстом, находит там имена классов, их членов, свойств, методов, процедур и функций, а затем связывает их с данными из наших комментариев с тегами. Из этой информации формируется документация в формате HTML, PDF, RTF или других.

При разработке библиотек и фреймворков обычно создается документация для API. Со временем она устаревает — в неё не успевают или просто забывают вносить изменения.

Когда нужны пояснения в коде, а когда — нет

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

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

/*
Устанавливаем значение 32 для переменной age
*/
int age = 32;

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

def calculate_si_amount(principal, rate, time):
  interest = (principal*rate*time)/100
##  Проверить, когда сумма превысит 2000
##  if principal+interest > 2000:
##     print(time) 
  return principal+interest

После отладки их лучше удалить, оставив строки:

def calculate_si_amount(principal, rate, time):
  interest = (principal*rate*time)/100
  return principal+interest

Но бывают исключения. Допустим, разработчик попробовал несколько вариантов решения и выбрал один, не самый очевидный. Потом забыл ход своих мыслей, открыл код и решил использовать «более правильный и оптимальный вариант». И тут он понимает, что новое решение хуже старого; более того, раньше он уже это пробовал делать. Приходится откатывать всё назад. Чтобы не попасть в такую ситуацию, пишите поясняющие комментарии.

Пример на языке JavaScript:

/* не используйте глобальную функцию isFinite(), потому что она возвращает true, если параметр value не имеет значения */ 
Number.isFinite(value)

Здесь и сам метод Number.isFinite (), и глобальная функция isFinite () проверяют, является ли параметр value конечным числом (то есть не ± ∞). Но если value = null, то isFinite (value) возвращает true, а Number.isFinite (value) возвращает false. Поэтому Number.isFinite (value) нельзя менять на isFinite (value).

Обязательно комментируйте код, если в нём есть какие-то тонкости и неочевидные вещи. Например:

/*
Рассчитываем стоимость товара
*/
cost = quantity * 2 * price;

Это неудачный комментарий: непонятно, зачем количество умножать на 2.

Правильно будет так:

/*
Умножаем количество на 2, т.к. этот товар продается в паре
*/
cost = quantity * 2 * price;

Комментарии в сложном коде и рефакторинг

В сложной и запутанной программе не обойтись без поясняющих комментариев. Но иногда лучше упростить сам код: разбить на отдельные функции, уменьшить размеры элементов, упростить циклы и так далее. А самим функциям, константам и переменным дать «говорящие» имена, объясняющие их назначение.

Например, есть метод, который сравнивает числа a и b. Если a > b, он возвращает true, a если a < b — false:

public boolean max(int a, int b) {
	if(a > b) {
    	return true;
	} else if(a == b) {
    	return false;
	} else {
    	return false;
	}
}

Весь этот громоздкий кусок кода можно значительно упростить, просто убрав блок if-else:

public boolean max(int a, int b) {
 	return a>b;
}

Теперь метод выглядит намного проще и элегантнее, хотя его суть не изменилась. Подобные преобразования называются рефакторингом.