Комментарии
Не весь код, который мы пишем, предназначен для непосредственного выполнения компьютером. Иногда нам нужно оставлять пояснения, заметки или временно отключать фрагменты кода. Для этого в программировании используются комментарии.
В Python комментарии начинаются с символа решетки #. Все, что следует за # до конца строки, интерпретатором игнорируется. Это позволяет добавлять в код объяснения или напоминания:
print("Привет, мир!") # Это комментарий, поясняющий, что делает эта строка
# print("Эта строка закомментирована и не будет выполнена")
Также в учебных материалах в комментариях часто указывают ожидаемый результат выполнения кода:
print("Привет, мир!")
# Вывод: Привет, мир!
Кроме пояснений, комментарии позволяют быстро отключить отдельные участки кода без их удаления:
# Раскомментируйте эту команду, чтобы вывести сообщение
# print("Заблокированное сообщение")
Но если символ # встречается внутри строки, то он рассматривается как её обычный символ и не интерпретируются как начало комментария:
print("Однострочный комментарий начинается с символа #")
Рекомендации PEP 8 по оформлению комментариев
Следование рекомендациям PEP 8 при написании комментариев делает код более читаемым и профессиональным.
1. Ставьте пробел между символом # и текстом комментария:
# Правильное пространство перед комментарием
2. Если комментарий размещён рядом с командой на одной строке, оставляйте 2 пробела между самой инструкцией и началом комментария:
x = 1 + 2 # Результат вычисления сохраняем в переменную x
3. Многострочные комментарии желательно располагать на уровне отступа блока кода, которому они принадлежат:
def my_function(x):
# Начинаем вычисление
if x > 0:
# Блок обработки положительных значений
result = x * 2
Многострочные комментарии
Иногда возникает необходимость записать более развернутое пояснение, которое не умещается в одну строку. Для этого можно разместить столько строк с символом #, сколько потребуется:
# Это пример многострочного комментария.
# Он используется для предоставления более подробного
# объяснения определенного участка кода или его логики.
print("Привет, мир!")
print("Всё ещё привет, мир!")
Однако удобнее использовать многострочные комментарии, создаваемые с помощью тройных одинарных ''' или двойных """ кавычек. Подобная конструкция позволяет создавать многострочную область, которая целиком воспринимается как один комментарий:
"""
Этот блок описывает работу модуля и служит примером стиля оформления
документации для крупных блоков кода.
"""
print("Всё ещё привет, мир!")
При этом многострочные комментарии не поддерживают вложенность. Попытка вложить один такой комментарий внутрь другого может привести к ошибке:
"""
Это внешний многострочный комментарий.
"""
Попытка вложить еще один многострочный комментарий не сработает!
"""
"""
Строки документации
Многострочные комментарии, заключенные в тройные кавычки, часто используются для написания строк документации (англ. – docstrings). Они служат для описания назначения и функциональности объектов Python, таких как модули, функции и классы. Эти конструкции похожи на многострочные комментарии, но имеют ключевое различие: они хранятся в памяти программы и могут использоваться инструментами разработки для создания документации.
Строки документации записываются сразу после определения класса, метода или функции и располагаются в пределах тройных кавычек:
def greet():
"""
Выводит на экран приветственное сообщение.
"""
print(f"Привет, друг!")
Чтобы просмотреть документацию любого элемента, достаточно вызвать встроенную функцию help():
help(greet)
Тогда на экране мы увидим строки документации, написанные ранее:
Help on function greet in module __main__:
greet(name)
Выводит на экран приветственное сообщение.
Также мы можем посмотреть документацию встроенной функции print():
help(print)
Как видите, встроенные функции имеют подробную документацию, описывающую их поведение:
Help on built-in function print in module builtins:
print(*args, sep=' ', end='\n', file=None, flush=False)
Prints the values to a stream, or to sys.stdout by default.
sep
string inserted between values, default a space.
end
string appended after the last value, default a newline.
file
a file-like object (stream); defaults to the current sys.stdout.
flush
whether to forcibly flush the stream.
Когда и что комментировать?
Комментарии должны помогать понять логику и назначение кода, поэтому следует приддерживаться определённых рекомендаций.
1. Добавляйте ясность там, где логика сложна или неочевидна:
# Алгоритм Евклида для нахождения НОД двух чисел
while a != b:
if a > b:
a -= b
else:
b -= a
2. Объясняйте причину выбора конкретного подхода или решения:
# Используем кэширование результатов для ускорения последующих обращений
@lru_cache(maxsize=128)
def fibonacci(n):
...
3. Документируйте функции, классы и модули:
def congratulate():
"""
Выводит на экран сообщение с поздравлением.
"""
print("Пусть твой день будет полон счастья и радости!")
4. Избегайте избыточного комментирования очевидных действий:
print("Привет, мир!") # Функция вывода сообщения "Привет, мир!" на экран
Хорошо написанные комментарии делают ваш код более понятным и облегчают его поддержку в будущем.
1. С какого символа начинается однострочный комментарий?
2. Для чего нужны комментарии?
3. Как можно написать комментарий, занимающий несколько строк?
4. Используя символ # и создайте простой комментарий на тему вашего любимого хобби или блюда.
5. Запишите свою любимую цитату или стихотворение в виде многострочного комментария.