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

В Python однострочные комментарии начинаются с символа решетки (#). Все, что следует за ним до конца строки, игнорируется интерпретатором. Это позволяет добавлять в код объяснения или напоминания:

print("Привет, мир!") # Это поясняющий комментарий

Также в комментариях можно указать ожидаемый результат выполнения кода:

print("Привет, мир!") 
# Вывод: Привет, мир!

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

# Раскомментируйте эту команду, чтобы вывести сообщение
# print("Заблокированное сообщение")

Но если символ # встречается внутри строки, то он рассматривается как её обычный символ и не интерпретируются как начало комментария:

print("Однострочный комментарий начинается с символа #")
# Вывод: Однострочный комментарий начинается с символа #

Рекомендации PEP 8 по оформлению комментариев

Следование рекомендациям PEP 8 при написании комментариев делает код более читаемым и профессиональным:

1. Ставьте пробел между символом # и текстом комментария:

# Правильное пространство перед комментарием

2. Если комментарий размещён рядом с командой на одной строке, оставляйте 2 пробела между самой инструкцией и началом комментария:

x = 1 + 2  # Результат вычисления сохраняем в переменную x

3. Комментарии желательно располагать на уровне отступа блока кода, которому они принадлежат:

def my_function(x):
    # Функция умножения на 2 положительных чисел
    if x > 0:
        # Блок обработки положительных значений
        result = x * 2

Многострочные комментарии

Иногда возникает необходимость записать более развернутое пояснение, которое не умещается в одну строку. Для этого можно разместить столько строк с символом #, сколько требуется:

# Это пример многострочного комментария. 
# Он используется для предоставления более подробного 
# объяснения определенного участка кода или его логики.
print("Всё ещё привет, мир!")
# Вывод: Всё ещё привет, мир!

Но вместо множества символов # для длинных комментариев часто используются многострочные строки, которые создаются с помощью тройных одинарных (''') или двойных (""") кавычек:

"""Этот блок описывает работу модуля и служит примером стиля оформления
документации для крупных блоков кода.
"""
print("Сколько можно приветствовать мир?")
# Вывод: Сколько можно приветствовать мир?

Технически это не комментарии, а строки, которые интерпретатор игнорирует, если они не присвоены переменной. Однако этот способ стал общепринятым для написания строк документации (англ. – docstrings). Они служат для описания назначения и функциональности объектов Python, таких как модули, функции и классы. Такие конструкции похожи на многострочные комментарии, но имеют ключевое различие: они хранятся в памяти программы и могут использоваться инструментами разработки для создания документации.

Когда и что комментировать?

Комментарии должны помогать понять логику и назначение кода, поэтому следует придерживаться определённых рекомендаций:

1. Объясняйте причину выбора конкретного подхода или решения:

# Используем кэширование результатов для ускорения
@lru_cache(maxsize=128)
def fibonacci(n):
    ...

2. Добавляйте ясность там, где логика сложна или неочевидна:

# Алгоритм Евклида для нахождения НОД двух чисел
while a != b:
    ...

3. Документируйте функции, классы и модули:

def congratulate():
    """Выводит на экран сообщение с поздравлением
    """
    print("Пусть твой день будет полон счастья и радости!")

4. Избегайте избыточного комментирования очевидных действий:

print("Привет, мир!")  # Вывод на экран сообщения "Привет, мир!"

Хорошо написанные комментарии делают код более понятным и облегчают его поддержку в будущем.

Итоги

  • Комментарии – это текст в коде, который игнорируется интерпретатором и не выполняется. Они используются для пояснений или временного отключения кода.
  • Однострочные комментарии начинаются с символа #.
  • Если комментарий размещён на той же строке, что и код, следует оставлять 2 пробела между инструкцией и символом #.
  • Между символом # и текстом комментария ставится 1 пробел.
  • Комментарии рекомендуется выравнивать по отступу блока кода.
  • Многострочные комментарии создаются с помощью тройных одинарных (''') или двойных (""") кавычек
  • Строки документации – это многострочные комментарии в тройных кавычках для описания модулей, функций и классов.

Задания для самопроверки

1. С какого символа начинается однострочный комментарий?

#.

2. Для чего нужны комментарии?

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

3. Как можно написать комментарий, занимающий несколько строк?

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

4. Используйте символ # и создайте простой комментарий на тему вашего любимого хобби или блюда.

# Винегрет

5. Запишите свою любимую цитату или стихотворение в виде многострочного комментария.

"""Матросская шапка,
Веревка в руке,
Тяну я кораблик
По быстрой реке,
И скачут лягушки
За мной по пятам
И просят меня:
– Прокати, капитан!
"""
 
Назад Далее