Многострочные комментарии в Python
В Python, для однострочных комментариев используется символ # . Но если нужно закомментировать большой блок кода, то приходится приписывать # в начале каждой строки. Это очень неудобно при отладке. Есть ли какая-то возможность использовать многострочные комментарии (аналог /* . */ из Си) в Python? UPD: Знаю, что различные IDE позволяют делать такие вещи автоматически, но хотелось бы более элегантного решения, не зависящего от средства редактирования кода и различных утилит.
Отслеживать
Dmitriy Simushev
задан 12 окт 2015 в 11:48
Dmitriy Simushev Dmitriy Simushev
17.9k 5 5 золотых знаков 48 48 серебряных знаков 85 85 бронзовых знаков
Как это сделать в VIM штатными средствами: stackoverflow.com/a/2561497
12 окт 2015 в 19:50
Мой вопрос сводится скорее к «как использовать многострочные комментарии в языке, где нет многострочных комментариев», а не к «как использовать редакторы кода для автоматического создания пачки однострочных комментариев»
13 окт 2015 в 11:16
5 ответов 5
Сортировка: Сброс на вариант по умолчанию
Насколько мне известно, отдельного синтаксиса для многострочных комментариев в Python нет. В тоже время, можно использовать строковые литералы, заключенные в тройные апострофы, например так:
''' Это строковый литерал. Но здесь он используется как многострочный комментарий ''' Строковые литералы, заключенные в тройные кавычки, могут содержать:
- кавычки ( » )
- апострофы ( ‘ )
- docstring комментарии ( «»»func desc»»» )
- переводы строк
В тоже время, стоит помнить, что такой строковый литерал не должен содержать внутри символов »’ . Это требование аналогично запрету на последовательность символов */ внутри многострочного комментария Си.
Кстати, этот же хак, предлагает использовать создатель языка Python в одном из своих твитов.
В тоже время, как верно отметил @jfs, руководство по стилю кода (pep-8) рекомендует использовать # для блочных комментариев.
Отслеживать
ответ дан 12 окт 2015 в 11:48
Dmitriy Simushev Dmitriy Simushev
17.9k 5 5 золотых знаков 48 48 серебряных знаков 85 85 бронзовых знаков
Действительно, это способ описан во всех (или почти всех) книгах о Python
12 окт 2015 в 12:11
Руководство по стилю кода (pep-8) рекомендует использовать # для блочных комментариев.
Но если нужно закомментировать большой блок кода, то приходится приписывать # в начале каждой строки. Это очень неудобно при отладке.
Один из явных признаков неумелого программирования — это наличие закомментированных фрагментов кода. Используйте систему контроля версий и/или ваше IDE, чтобы временно убрать/закомментировать код при отладке. Настройте ваше окружение, чтобы вы могли это делать не задумываясь, нажимая пару клавиш.
Знаю, что различные IDE позволяют делать такие вещи автоматически, но хотелось бы более элегантного решения, не зависящего от средства редактирования кода и различных утилит.
Закомментированный код не должен добавляться в систему контроля версий, поэтому для временных изменений, которые не переживут одну сессию редактирования кода, один клавишный аккорд (например, M-; в Emacs), как правило, достаточен, чтобы закомментировать/раскомментировать кусок кода.
«»»multiline string literal»»» не является многострочным комментарием в Питоне. Это просто строковая константа, которая позволяет использовать буквальные символы новой строки без экранирования (такого как \n ). Часто используется для описаний модулей, классов, функций/методов прямо в коде:
>>> def f(): . """abc""" . >>> f.__doc__ 'abc' Попытка использовать «»»»»» в качестве многострочного комментария сломается на первой docstring, даже если бы не было других более подходящий решений для данной задачи.
Комментарии в Python
Комментарии – способ прокомментировать код на ходу, на той же строке. Вот пример кода. Здесь, “Получил пользователя” – это комментарий.
user = get_user_by_id(...) # Получил пользователя Такие комментарии начинаются с символа # . Можно добавить комментарий на отдельной строке:
# Получил пользователя user = get_user_by_id(...) Комментарии ничего не делают, это просто заметки, которые можно оставлять прямо внутри программы.
Иногда программисты комментируют код, чтобы он перестал работать, но при этом не потерять его из виду:
# Получил пользователя # user = get_user_by_id(. )
Докстринги
Докстринг – строковая переменная, которая идёт сразу за объявлением функции, класса, метода или модуля. Она нужна для документирования всей функции: описания входящих параметров, результата, логики, крайних случаев. Заключается в тройные двойные кавычки. Вот так:
def tensorsolve(a, b, axes=None): """ Solve the tensor equation ``a x = b`` for x. It is assumed that all indices of `x` are summed over in the product, together with the rightmost indices of `a`, as is done in, for example, ``tensordot(a, x, axes=len(b.shape))``. """ В серьёзных проектах из них часто генерируется документация, поэтому они могут быть большими, по несколько экранов. Это касается проектов, у которых есть документация для разработчиков: Django, numpy, sqlalchemy.
Если проект не подразумевает, что им будут пользоваться другие разработчики, такого быть не должно. Длинных докстрингов не должно быть в скрипте ресайза изображений, сайте блога или алгоритме обучения нейронной сети.
Прямо в докстрингах можно писать короткие тесты, их называют доктесты. Ни разу не видел, чтобы кто-то это использовал в боевом проекте.
Как не использовать
Дублировать информацию из кода
Самая частая ошибка, связанная с комментариями: дублирование информации. В таком случае комментарий не несёт дополнительной информации, а просто переводит соседний код с Питона на русский/английский. Пример:
# загружаем данные из файла data.json with open('users.json', 'r') as handler: data = json.load(handler) Вот как можно исправить:
with open('users.json', 'r') as handler: data = json.load(handler) А так – ещё лучше:
data = load_all_users_from_file() Не поддерживать комментарии
Другая частая ошибка: не менять комментарии при изменении кода. В примере выше мы загружали данные из файла. Через месяц взялись за голову и поселили данные в базе данных. Код стал таким:
# загружаем данные из файла data.json data = db_session.query(User).all() Данные из файла? WAT?
Думать, что все поймут
Когда программист пишет кусок кода, он глубоко в него погружён: держит в голове все детали, связи и особые случаи. В таком состоянии всё поведение кажется понятным, поэтому разработчик может оставить комментарий самому себе. Проблема в том, что когда он переключится на другую задачу и забудет про детали, комментарий может взорвать мозг:
inv(strain_tensor) - rigidity.T # правый случай Правый, правда? Ну, теперь всё понятно.
Шутить
Шутки к неидеальному коду смотрятся неуместно. Представь, как чувствует себя разработчик, копающийся в чужом коде три часа и находящий новый модуль с заглавным комментарием оставь надежду, всяк сюда входящий . Не будь автором этого комментария. Лучше наведи порядок в своём коде.
Как использовать
Вот хорошие причины использовать комментарии:
- объяснить неочевидное поведение: бывает, что нужно объяснить какой-нибудь подводный камень куска кода или объяснить поведение в особом случае; использовать только если ту же информацию в коде поселить нельзя или очень сложно;
- оставить напоминание себе или коллеге: речь про комментарии вроде TODO: кешировать ответ ручки или FIXME: учитывать часовой пояс .
Прежде чем написать комментарий, попробуй поселить его в коде, указав параметр или дав подходящее название переменной.
Что изучать
- Доклад Григория Петрова про комментирование исходников. Обязателен к просмотру.
- PEP 257. ПЕП про докстринги.
- doctest. Документация к модулю про доктесты.
- What is the best comment in source code you have ever encountered?. Шутить в коде не стоит, а вот посмеяться с чужих шуток можно. Это ж не нам поддерживать.
Попробуйте бесплатные уроки по Python
Получите крутое код-ревью от практикующих программистов с разбором ошибок и рекомендациями, на что обратить внимание — бесплатно.
Переходите на страницу учебных модулей «Девмана» и выбирайте тему.
Написание комментариев в Python 3
Комментарии – это строки, которые существуют в коде программы, но игнорируются компиляторами и интерпретаторами. Комментарии делают код более удобочитаемым, так как позволяют предоставить пользователям дополнительную информацию или добавить объяснение того или иного блока кода.
В зависимости от цели программы комментарии могут служить в качестве примечаний. Также с их помощью вы можете объяснить другим программистам, что делает та или иная часть кода программы.
Комментарии в программу рекомендуется добавлять по мере написания или обновления кода, так как позже вы можете пропустить что-то важное.
Синтаксис комментариев
Комментарии в Python начинаются с хеша (символа #), после которого ставится пробел.
Общий вид комментария:
# This is a comment
Строки комментариев не выполняются, потому при запуске программы вы не увидите никаких признаков наличия в ней комментариев. Комментарии находятся в исходном коде для простоты чтения кода программы другими пользователями, а не для выполнения.
В простейшей программе «Hello, World!» комментарий может выглядеть так:
# Print “Hello, World!” to console
print(«Hello, World!»)
В цикле for, который итерирует списки, могут быть такие комментарии:
# Define sharks variable as a list of strings
sharks = [‘hammerhead’, ‘great white’, ‘dogfish’, ‘frilled’, ‘bullhead’, ‘requiem’] # For loop that iterates over sharks list and prints each string item
for shark in sharks:
print(shark)
При размещении комментария следует учитывать отступы в коде, для которого он предназначен. То есть, если определение функции не имеет отступов, то и комментарий к этому определению не должен иметь отступов.
Для примера рассмотрим функцию again() из руководства Написание простейшего калькулятора в Python 3:
.
# Define again() function to ask user if they want to use the calculator again
def again():
# Take input from user
calc_again = input(»’
Do you want to calculate again?
Please type Y for YES or N for NO.
»’)
# If user types Y, run the calculate() function
if calc_again == ‘Y’:
calculate()
# If user types N, say good-bye to the user and end the program
elif calc_again == ‘N’:
print(‘See you later.’)
# If user types another key, run the function again
else:
again()
Комментарии должны помогать программистам работать с кодом. Если же по какой-либо причине вы не можете предоставить должную поддержку и своевременное обновление комментариев, лучше их вообще не использовать. Код без комментариев лучше, чем код с неправильными комментариями.
В комментарии рекомендуется указывать, почему этот код выполняет то или иное действие (а не как или что он делает). В большинстве случаев программист, ознакомившись с кодом, может сам определить, что именно выполняет код и каким образом он это делает.
Блочные комментарии
Блочные комментарии могут объяснить более сложный код или код, с которым пользователям будет трудно разобраться самостоятельно. Такой блок комментариев должен иметь столько же отступов, сколько блок кода, который он объясняет.
В блочных комментариях каждая строка начинается с хеша и пробела. Чтобы разделить блок комментариев на абзацы, поставьте с новой строки хеш и оставьте строку пустой.
Следующий блочный комментарий описывает действия функции main().
# The main function will parse arguments via the parser variable. These
# arguments will be defined by the user on the console. This will pass
# the word argument the user wants to parse along with the filename the
# user wants to use, and also provide help text if the user does not
# correctly pass the arguments.
def main():
parser = argparse.ArgumentParser()
parser.add_argument(
«word»,
help=»the word to be searched for in the text file.»
)
parser.add_argument(
«filename»,
help=»the path to the text file to be searched through»
)
.
Блочные комментарии обычно используются в случае, если код требует подробного объяснения. Однако следует избегать чрезмерного количества комментариев в коде программы.
Строчные комментарии
Строчные комментарии следуют за кодом (то есть, находятся в одной строке с теми выражениями, которые они объясняют).
Строчный комментарий выглядит так:
# Inline comment about the code
Строчные комментарии позволяют дать краткое объяснение для непонятной части кода, однако их нужно использовать с осторожностью. Часто их используют в качестве кратких примечаний для других пользователей.
Например, если вы предполагаете, что другие разработчики из вашей команды не знают, что следующее выражение создает комплексное число, вы можете добавить строчный комментарий:
z = 2.5 + 3j # Create a complex number
Также строчный комментарий может объяснить, почему вы используете здесь тот или иной элемент:
x = 8 # Initialize x with an arbitrary number
Строчные комментарии следует использовать крайне редко.
Комментирование кода перед тестированием
Кроме документации кода, комментарии также используются в тестировании программ. К примеру, так вы можете закомментировать ту часть кода, которую не нужно обрабатывать во время проверки программы. Если после внедрения нового кода программа выдаёт ошибки, вы можете закомментировать некоторые строки нового кода, чтобы узнать, в чём проблема.
Кроме того, комментарии позволяют вам добавить в код несколько альтернативных блоков и проверить, какой из них вам подходит больше. Например, вы можете добавить в программу цикл while и цикл for, а затем с помощью комментариев проверить работу каждого из них в отдельности и выбрать тот, что подходит больше.
import random
number = random.randint(1, 25)
# number_of_guesses = 0
for i in range(5):
# while number_of_guesses < 5:
print(‘Guess a number between 1 and 25:’)
guess = input()
guess = int(guess)
# number_of_guesses = number_of_guesses + 1
if guess < number:
print(‘Your guess is too low’)
if guess > number:
print(‘Your guess is too high’)
if guess == number:
break
if guess == number:
print(‘You guessed the number!’)
else:
rint(‘You did not guess the number. The number was ‘ + str(number))
Читайте также:
- Циклы while в Python 3
- Циклы for в Python 3
С помощью символа # вы можете протестировать несколько вариантов кода, обнаружить ошибки или запустить только ту часть кода, которая нуждается в дополнительной проверке.
Заключение
Благодаря комментариям код программы становится удобочитаемым и понятным. Это упрощает взаимодействие других разработчиков с кодом ваших программ.
Читайте также: PEP 257
№28 Как писать комментарии / для начинающих
Добавление комментариев считается хорошей практикой. Это неисполняемые, но все равно важные части кода. Они не только помогают программистам, работающим над одним и тем же проектом, но также тестировщикам, которые могут обращаться к ним для ясности при тестировании белого ящика.
Куда лучше добавлять комментарии при создании или обновлении программы, иначе можно утратить контекст. Комментарии, добавленные позже, могут быть далеко не настолько эффективными.
Комментарии — это способ выражения того, что делает программа на самом высоком уровне. Это отмеченные строчки, которые комментируют код. В Python они бывают двух типов: одно- и многострочные.
Однострочные комментарии в Python
Такой тип комментариев нужен для написания простых, быстрых комментариев во время отладки. Такие комментарии начинаются с символа решетки # и автоматически заканчиваются символом окончания строки (EOL).
# Хороший код документируется print("Изучите Python шаг за шагом!")При добавлении комментария важно убедиться, что у него тот же уровень отступа, что и у кода под ним. Например, нужно оставить комментарий к строке объявления функции, у которой нет отступа. Однако они имеются у блоков кода внутри нее. Поэтому учитывайте выравнивание при комментировании внутренних блоков кода.
# Создадим список месяцев
months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
'Jul','Aug','Sep','Oct','Nov','Dec']
# Функция вывода календарных месяцев
def showCalender(months):
# Цикл for проходит по списку и вводит название каждого месяца
for month in months:
print(month)
showCalender(months)Многострочные комментарии в Python
Python позволяет писать комментарии на нескольких строках. Они называются многострочными или блочными. Такой тип комментирования подходит для описания чего-то более сложного.
Этот тип комментариев нужен для описания всего последующего кода. Дальше примеры многострочных комментариев в Python.
С помощью символа #
Для добавления многострочного комментария нужно начинать каждую строку с символа решетки и одного пробела. Такой комментарий можно разбить на абзацы. Для этого достаточно добавлять пустые строки с символом перед каждым из них.
Примечание: в оригинале этот символ (#) называется octothorpe, что переводится с латинского как «восемь концов». Термин придумала группа инженеров в Bell Labs, которая работала над проектом первой сенсорной клавиатуры.
# Чтобы выучить любой язык, вы должны следовать этим правилам.
# 1. Знать синтаксис, типы данных, структуры и условные операторы.
# 2. Изучить обработку ошибок и ввод/вывод.
# 3. Читайте о продвинутых структурах данных.
# 4. Пишите функции и следуйте концепциям ООП.
def main():
print("Начнем изучать Python.")Docstring в Python
В Python есть такая особенность, как задокументированные строки (docstring). С их помощью программисты могут быстро добавлять комментарии для каждого модуля, функции, метода или класса в Python.
Задать docstring можно с помощью строковой константы. Она обязана быть первой инструкцией в определении объекта.
У docstring более широкая область применения, чем у комментария. Она должна описывать, что делает функция, а не как. Хорошей практикой считается добавление таких строк в каждую функцию программы.
Как задать docstring в Python?
Задать docstring в Python можно с помощью тройных кавычек Нужно добавить один набор в начале и еще один – в конце. Docstring также могут занимать по несколько строк.
Примечание: строки с тремя кавычками также являются docstring в Python, пусть они и могут казаться обычными комментариями.
В чем отличие между комментарием и docstring?
Строки, начинающиеся с тройной кавычки, — это все еще обычные строки, которые могут быть написаны в несколько строк. Это значит, что они все еще являются исполняемыми инструкциями. Если же у них нет метки, значит сборщик мусора уничтожит их после исполнения.
Интерпретатор Python не будет игнорировать их так же, как комментарии. Но если такая строка расположена сразу же после объявления функции или класса в верхней части модуля, то она станет docstring. Получить к ним доступ можно следующим образом — myobj.__doc__ .
def theFunction():
'''
Эта функция демонстрирует использование docstring в Python.
'''
print("docstring python не являются комментариями.")
print("\nВыведем docstring функции. ")
print(theFunction.__doc__)Выводы
Комментарии и docstring добавляют ценности программе. Они делают программы более читаемыми и пригодными для последующей поддержки. Даже при рефакторинге сделать это будет намного проще с комментариями.
Разработка программного обеспечения — это лишь на 10% написание кода. Остальные 90% — поддержка.
Поэтому всегда добавляйте осмысленные комментарии и docstring, потому что они упрощают процесс взаимодействия и ускоряют процесс рефакторинга.
- ТЕГИ
- Уроки Python для начинающих