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

Наверное не раз при чтении лекций в примерах кода вы видели строки типа.

#какой-то текст...

В этой небольшой лекции мы разберемся с тем что это, и с чем это едят.

Что такое комментарии в коде?

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

Комментарии могут быть однострочными и многострочными:

Однострочные комментарии начинаются с символа # (в Python). Всё, что написано после этого символа до конца строки, игнорируется интерпретатором.

Многострочные комментарии можно создавать, используя тройные кавычки """ в Python. Всё, что находится между этими кавычками, также игнорируется интерпретатором.

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

Понятность кода: Комментарии помогают другим программистам (и самому себе в будущем) понять, как работает код, особенно если он сложный или нестандартный.

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

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

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

Как правильно использовать комментарии?

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

Объясняйте, зачем код делает что-то, а не как. Если часть кода выполняет определённую логику, комментарии должны объяснять, зачем это делается, а не повторять то, что уже ясно из самого кода.

# Проверяем, есть ли пользователь с таким именем в базе данных
if user_exists(username):
    # Если пользователь найден, выводим сообщение об ошибке
    print("Пользователь уже существует")

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

# Устанавливаем значение переменной a в 5
a = 5  # Не нужно такого комментария

Обновляйте комментарии вместе с кодом. Комментарии должны быть актуальными. Если код изменился, не забудьте изменить и соответствующие комментарии.

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

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

Описание функции:

def calculate_total(price, tax):
    """
    Вычисляет общую стоимость с учетом налога.

    :param price: исходная цена товара
    :param tax: налоговая ставка в процентах
    :return: общая стоимость с налогом
    """
    return price + (price * tax / 100)

*С функциями и конструкцией if мы познакомимся позже, здесь мы вас знакомим только с комментариями.

Многострочный комментарий в любом участке кода:

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

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