как быстро закомментировать код в python

Использование комментариев в Python

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

Введение

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

Комментарии позволяют писать заметки и пояснять код прямо внутри программы.

Комментарии используются там, где код недостаточно понятен сам по себе. По сути, это операторы или строки, игнорируемые интерпретаторами Python.

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

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

Открой для себя мир моментальных анонсов новых статей.

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

Создание комментария

Чтобы написать комментарий, начните строку с символа #. Python проигнорирует все, что будет написано после него. Как правило, комментарии выглядят примерно так:

Комментарии также можно размещать в конце строки:

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

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

Если строка не привязана к какой-либо переменной, Python прочитает ее как код, но в итоге проигнорирует.

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

Иногда программисты, работающие с Python, ставят символ # перед строчкой кода, чтобы временно удалить ее из программы на время проверки. Этот прием называется «закомментировать код» и пригождается в тех случаях, когда вы пытаетесь выяснить, почему программа не работает. Закончив проверки, вы можете быстро вернуть код обратно, просто удалив поставленный перед строчкой символ #.

Заключение

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

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

Источник

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

На этот вопрос уже есть ответ здесь:

Есть ли механизм для комментирования больших блоков кода Python?

Проблема с этим заключается в том, что вставка # перед каждой строкой является громоздкой и «»» заставляет строку, которую я хочу использовать в качестве комментария, отображаться в сгенерированной документации.

После прочтения всех комментариев ответ кажется «Нет».

15 ответов

Скрыть тройные кавычки в контексте, который не будет принят за строку документации, например:

В режиме визуального блока I перемещается в режим вставки с курсором перед блоком в его первой строке. Вставленный текст копируется перед каждой строкой в ​​блоке.

Да, есть (в зависимости от вашего редактора). В PyDev (и в Aptana Studio с PyDev):

Кстати, Notepad ++ прекрасно работает как редактор Python. С автозаполнением, свертыванием кода, подсветкой синтаксиса и многим другим. И это бесплатно, как в речи, так и в пиве!

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

Другое решение на основе редактора: текстовые «прямоугольники» в Emacs.

Выделите код, который вы хотите закомментировать, затем C-x-r-t #

Чтобы откомментировать код: выделите, затем C-x-r-k

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

Тройные кавычки в порядке для меня. Вы можете использовать » ‘foo’ » для строк документации и «» «bar» «» для комментариев или наоборот, чтобы сделать код более читабельным.

Если у вас нет редактора, который поддерживает комментарии к блоку, вы можете использовать строку в тройных кавычках в начале и в конце блока кода, чтобы «эффективно» закомментировать его. Это не лучшая практика.

Источник

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

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

5 ответов 5

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

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

Кстати, этот же хак, предлагает использовать создатель языка Python в одном из своих твитов.

В тоже время, как верно отметил @jfs, руководство по стилю кода (pep-8) рекомендует использовать # для блочных комментариев.

Руководство по стилю кода (pep-8) рекомендует использовать # для блочных комментариев.

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

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

Закомментированный код не должен добавляться в систему контроля версий, поэтому для временных изменений, которые не переживут одну сессию редактирования кода, один клавишный аккорд (например, M-; в Emacs), как правило, достаточен, чтобы закомментировать/раскомментировать кусок кода.

«»»multiline string literal»»» не является многострочным комментарием в Питоне. Это просто строковая константа, которая позволяет использовать буквальные символы новой строки без экранирования (такого как \n ). Часто используется для описаний модулей, классов, функций/методов прямо в коде:

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

Источник

Написание комментариев в Python 3

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

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

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

Синтаксис комментариев

Комментарии в Python начинаются с хеша (символа #), после которого ставится пробел.

Общий вид комментария:

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

В простейшей программе «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 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))

Читайте также:

С помощью символа # вы можете протестировать несколько вариантов кода, обнаружить ошибки или запустить только ту часть кода, которая нуждается в дополнительной проверке.

Заключение

Благодаря комментариям код программы становится удобочитаемым и понятным. Это упрощает взаимодействие других разработчиков с кодом ваших программ.

Источник

Как улучшить код на Python: приёмы рефакторинга

Чтобы код оставался понятным, в нём регулярно надо убираться. Рассказываем, что и где прибирать.

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

Чтобы не допустить этого, при разработке периодически проводят рефакторинг — вносят изменения, которые делают код понятнее, но не меняют его функциональность.

Важно! Рефакторинг более эффективен и безопасен, когда пошаговые изменения проверяются запусками тестов.

Если вы только-только столкнулись с рефакторингом — сперва прочтите эту статью.

Программист, консультант, специалист по документированию. Легко и доступно рассказывает о сложных вещах в программировании и дизайне.

Убираем мусор в коде

В языке Python есть много приёмов улучшения кода. Однако перед тем, как применять более сложные, нужно почистить код от накопившегося мусора.

Закомментированный код

Удаляйте закомментированные куски кода. Они сбивают с толку разработчиков, которые работают с исходниками после вас.

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

Отладочные команды print()

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

Ненужные команды импорта

Допустим, вы попробовали вариант решения с использованием каких-то модулей, потом пошли по другому пути и модули более не нужны.

Не забудьте удалить из кода соответствующие команды импорта — обычно редакторы их подсвечивают. Так, в IDE PyCharm текст команды становится бледным и при компиляции выдаётся предупреждение «Unused import statement…».

Неиспользуемые переменные

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

Найти эти переменные легко — редакторы их подсвечивают, а при компиляции выдаётся предупреждение: «Variable is not used».

Здесь PyCharm выделяет серым и ненужный модуль os, и неиспользуемые переменные unused1 и unused2.

Улучшаем читаемость кода

Проводя рефакторинг, важно оформить код так, чтобы его было удобно читать.

Создатель языка Python Гвидо ван Россум сказал: «Код читают гораздо чаще, чем пишут».

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

Гвидо ван Россум считал удобочитаемость одним из важнейших принципов языка Python. Поэтому вместе с соратниками разработал свод рекомендаций по оформлению кода — PEP 8. Рассмотрим некоторые из них подробнее.

Имена переменных

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

Например, имя переменной в выражении sc += 1 нам мало о чём говорит.

А если изменить его на score, то станет ясно, что речь идёт о счёте.

Есть два важнейших правила именования сущностей в Python — их нарушение вызывает ошибку:

PEP 8 предписывает задавать имена определённым образом:

Например: pyclbr, py_compile.

Форматирование кода

Обнаружить ошибки форматирования помогают специальные программы — линтеры. Они анализируют код и выдают предупреждения, например:

Источник