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

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

Комментарии — аннотации, которые делают код более доступным и удобным для чтения и понимания.

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

Когда комментарии — хорошая идея?

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

Вот главные плюсы использования этого инструмента:

• Сохранение знаний. Разработчики могут приходить и уходить из проекта, но хорошие комментарии остаются — помогают передать знания о коде новым членам команды.

• Улучшение взаимоотношений. Хорошие и полезные комментарии помогают создать более дружелюбную и продуктивную атмосферу в команде.

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

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

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

Выделяют несколько типов комментариев, у каждого из них — своя роль в объяснении и документировании кода. Сгруппируем их по смыслу и рассмотрим на примерах.

Поясняющие комментарии

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

Пример кода на Python с поясняющими комментариями, объясняющими алгоритм сортировки пузырьком:

			def bubble_sort(arr):
    """
    Функция для сортировки списка методом пузырька.

    Args:
        arr (list): Список, который нужно отсортировать.

    Returns:
        list: Отсортированный список.
    """
    n = len(arr)

    # Внешний цикл: проходим по всем элементам списка
    for i in range(n):
        # Внутренний цикл: переставляем максимальный элемент в конец списка
        # После каждой итерации внутреннего цикла наибольший элемент "всплывает" на правильную позицию
        for j in range(0, n - i - 1):
            if arr[j] > arr[j + 1]:
                # Обмен значениями, чтобы максимальный элемент переместился в конец
                arr[j], arr[j + 1] = arr[j + 1], arr[j]

    return arr

# Пример использования функции сортировки
unsorted_list = [64, 34, 25, 12, 22, 11, 90]
sorted_list = bubble_sort(unsorted_list)
print("Отсортированный список:", sorted_list)
		

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

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

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

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

Вот некоторые примеры документирующих комментариев:

• Описание неочевидных классов и методов. Документирующие комментарии предоставляют информацию о назначении, параметрах и возвращаемых значениях методов и функций.
• Генерация документации. Документирующие комментарии предназначены для автоматической генерации документации к коду и часто используются с инструментами типа Doxygen (для C++, C и других языков), Javadoc (для Java) и docstrings (для Python).

Допустим, у нас есть класс, реализующий алгоритм решения квадратного уравнения на Python:

			import math

class QuadraticSolver:
    """
    Класс для решения квадратных уравнений.
    """

    def __init__(self, a, b, c):
        """
        Конструктор для создания объекта решателя квадратных уравнений.

        Args:
            a (float): Коэффициент a.
            b (float): Коэффициент b.
            c (float): Коэффициент c.
        """
        self.a = a
        self.b = b
        self.c = c

    def solve(self):
        """
        Решить квадратное уравнение.

        Returns:
            tuple: Корни уравнения в виде кортежа (x1, x2).
        """
        discriminant = self.b ** 2 - 4 * self.a * self.c
        if discriminant < 0:
            return None # Нет действительных корней

        x1 = (-self.b + math.sqrt(discriminant)) / (2 * self.a)
        x2 = (-self.b - math.sqrt(discriminant)) / (2 * self.a)
        return x1, x2

# Пример использования класса
solver = QuadraticSolver(1, -3, 2)
roots = solver.solve()

if roots:
    print(f"Корни уравнения: x1 = {roots[0]}, x2 = {roots[1]}")
else:
    print("Уравнение не имеет действительных корней.")
		

Здесь документирующие комментарии описывают назначение класса QuadraticSolver, параметры его конструктора, метод solve() для решения уравнения и формат возвращаемых значений. Эта документация помогает понять, как использовать класс для решения квадратных уравнений, при этом она не избыточна и охватывает ключевые аспекты функциональности кода.

Отладочные и временные комментарии

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

#TODO: Планирование рефакторинга

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

#FIXME: Исправление проблем

Комментарий #FIXME используют, когда обнаружили проблему или баг в коде, который нужно исправить. Этот тег помогает указать на участок кода, который может вызвать проблемы.

#Warning: Осторожный запуск

Тег #Warning подразумевает, что перед запуском соответствующего участка кода нужно быть осторожным из-за возможных проблем.

#Error: Обозначение ошибки

Комментарий #Error используют, чтобы указать на ошибки в коде. Здесь вы можете объяснить проблему и причину, почему её не удалось решить.

Пример кода с отладочными комментариями на Java:

			public class Calculator {
    public static void main(String[] args) {
        int num1 = 10;
        int num2 = 0;
        int result = divide(num1, num2);
        if (result != Integer.MIN_VALUE) {
            System.out.println("Результат деления: " + result);
        } else {
            System.out.println("Ошибка: деление на ноль.");
        }
    }
    public static int divide(int a, int b) {
        if (b == 0) {
            // FIXME: Обработать случай деления на ноль
            return Integer.MIN_VALUE;
        }
        // TODO: Добавить логирование перед выполнением деления
        // System.out.println("Делим " + a + " на " + b);
        int result = a / b;
        return result;
    }
}
		

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

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

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

Вот несколько практик, про которые нужно помнить:

• Комментарии должны отвечать на вопрос «почему» и объяснять причины, алгоритмы и принятые решения, а не просто повторять код. Код сам по себе описывает, «что» он делает, а комментарии помогают понять, «почему» и «как».

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

• Соблюдайте стиль. Следуйте единообразному стилю комментирования в вашем проекте. Это поможет сохранить код читаемым и профессиональным.

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

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

• Включайте контекст. Если код связан с какой-либо задачей, багом или требованием, включите ссылку на соответствующий номер или описание, чтобы разработчики могли понять, почему определённое решение было принято.

• Код-ревью и коллективная работа. Практика код-ревью — отличный способ улучшить качество комментариев. Отзывы и рекомендации от коллег могут помочь выявить недостаточно понятные комментарии или предложить альтернативные способы их написания.

Когда комментарии в коде — плохая затея?

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

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

• Очевидные детали и стандартные конструкции. Не стоит комментировать простые и хорошо известные аспекты кода, которые понятны из его структуры. Комментарии, объясняющие базовые элементы языка программирования (например, что такое “for” или “if”), будут лишними.
• Неудачные попытки пояснения. Иногда попытка написать комментарий может только запутать, если код плохо структурирован. Вместо этого попробуйте улучшить сам код, чтобы необходимость в объяснении отпала.

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

• Негативные комментарии. Не стоит выражать негодование или критику чужого кода — комментарии не предназначены для этого. Обсудить ход работы и качество кода лучше напрямую с разработчиком.

Подведём итог

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

Написание хороших комментариев — баланс между полезным объяснением кода и избеганием избыточности.

Кто умеет писать хорошие комментарии, поделитесь опытом, как к этому пришли.