Как комментировать блок кода в Python

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

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

为什么Python中的块注释很重要？

Комментарии, как правило, являются одним из первых понятий, с которыми вы сталкиваетесь в процессе обучения Python.彼ら обеспечивают полезную информацию о намерении задать определённый фрагмент кода. Они предлагают ясность и контекст по поводу того, почему скрипт ведет себя так. Есть ряд важных причин, по которым вы всегда должны использовать комментарии в ваших скриптах. Вот четыре из них:

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

Использование однострочных блочных комментариев в Python

Прежде чем погружаться в комментирование многострочных блоков, начнем с основ однострочных комментариев single-line comments. В Python однострочный комментарий начинается с символа решётки (#), и интерпретатор Python игнорирует все, что идёт за ним в той же строке. Чтобы создать однострочный комментарий, следуйте инструкциям ниже:

1. Размещение: Поместите символ # в начале строки или после кода в той же строке. Комментарии могут быть помещены над описываемым кодом, справа от кода в той же строке или быть самостоятельными.
2. Содержание: После символа # напишите свой комментарий. Это может быть объяснение строки кода, заметка для будущего использования или любая другая полезная информация, связанная с кодом.

# Это однострочный комментарий, объясняющий следующую строку кода
print("Hello, world!")  # Это выводит сообщение в консоль

Метод №1: Комментирование с помощью множества однострочных символов #

Самый простой способ комментировать в Python — использовать символ #, который комментирует все, что идет после него на строке. Хотя в Python нет специального синтаксиса для блочных комментариев, вы можете использовать несколько символов #, чтобы комментировать каждую строку по отдельности. Все, что вам нужно сделать, это выполнить следующие шаги:

1. Определите блок кода: Сначала определите блок кода, который вы хотите закомментировать. Это может быть функция, цикл или любой сегмент вашего кода, который вы хотите отключить или объяснить.
2. Закомментируйте каждую строку: Поместите символ # в начале каждой строки, которую вы хотите закомментировать. Это говорит интерпретатору Python игнорировать эти строки при выполнении.

Вы можете увидеть пример ниже:

# Пример комментирования нескольких строк по отдельности 
# def example_function(name):
#	# Эта функция печатает "Hello " и введенное имя
# 	print("Hello", name)

Метод блочного комментирования в Python #2: Комментирование с использованием строковых литералов в тройных кавычках

Существует альтернативный метод закомментирования нескольких строк, который заключается в использовании строковых литералов с тройными кавычками (”’ ”’ или “”” “””). Хотя они официально не являются блоками комментариев, такие строковые литералы часто используются как таковые, особенно для многострочных комментариев или docstrings. Чтобы использовать строки с тройными кавычками, просто поместите ”’ или “”” перед и после блока кода, который вы хотите закомментировать, следующим образом:

'''
def example_function(name):
	print("Hello", name)
'''

Строковые литералы с тройными кавычками наиболее часто используются для документирования функций Python. Например:

# Создать example_function()
def example_function(name):
	'''
	This function takes as input a name, and returns a salutation to the name in the form of "Hello name"
	'''
	# Вывести вывод 
	print("Hello", name)

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