При написании кода Python всегда рекомендуется делать его чистым и понятным. Организовать код, дать переменным и функциям описательные имена — вот несколько способов сделать это.
Еще один способ улучшить читаемость вашего кода — использовать комментарии. Комментарий — это понятное для человека объяснение или аннотация, которые используются для объяснения кода. Например, если вы написали сложное регулярное выражение, вы добавляете комментарий, описывающий, что делает код.
Добавление комментариев к вашему коду Python сэкономит вам много времени и усилий, если вы посмотрите на свой код в будущем. Допустим, вы хотите изменить сценарий, написанный несколько месяцев или лет назад. Скорее всего, вы не вспомните, почему вы написали какой-то сложный фрагмент кода, если не добавили комментарий. Комментарии также помогают другим разработчикам понять ваш код и его назначение.
Комментарии должны быть краткими и по существу. Не объясняйте то, что очевидно читателю.
В этой статье рассматриваются основы написания комментариев в Python.
Содержание
Написание комментариев на Python
Python игнорирует все, что написано в строке после решетки ( # ).
Комментарии могут быть добавлены в начале строки или встроены в другой код:
# This is a Python comment.
print("Hello World") # This is an inline Python comment.
Пробел после решетки не является обязательным, но он улучшит читаемость комментария.
Символ решетки в строковом литерале не указывает на начало строки комментария. Это просто символ решетки:
paragraph = "# Hash inside quotes is not a comment."
Comments should be at the same indent level as the code beneath it:
```py
def factorial(n):
if n == 0:
return 1
else:
# Use the factorial function
return n * factorial(n-1)
Если ваш текстовый редактор поддерживает выделение синтаксиса, комментарии обычно отображаются зеленым цветом.
Комментарии также полезны при отладке скрипта. Вместо удаления некоторых строк или блоков вы можете закомментировать их:
# for fruit in fruits:
# print(fruit)
Многострочные комментарии в Python (блоки комментариев)
В отличие от других популярных языков программирования, Python поддерживает только однострочные комментарии.
Самый простой способ написать многострочные комментарии в Python — это добавить однострочные комментарии один за другим:
# This is the first line.
# This is the second line.
Другой вариант — использовать строки документации .
Строки документации — это многострочные строковые литералы, которые используются для документирования того, что делает модуль, функция, класс или метод.
Строка документации начинается и заканчивается тройными двойными кавычками ( """ ) и может занимать одну или несколько строк:
"""This is
a multiline
docstring.
"""
Строки документации технически не являются комментариями. Когда строка документации встречается в качестве первого оператора в модуле, функции, классе или методе, она заканчивается в байт-коде и становится специальным атрибутом __doc__ этого объекта. Вы должны предпочесть использовать обычные однострочные хеш-комментарии.
Шебанг
Если вы читаете сценарии Python, вы можете заметить, что в некоторых из них первая строка начинается с символа #! символы и путь к интерпретатору Python:
#!/usr/bin/env python3
Эта последовательность символов называется shebang и используется для указания операционной системе, какой интерпретатор использовать для анализа остальной части файла. Сценарии, которые начинаются с shebang и являются исполняемыми, можно запускать в терминале, не вводя python перед именем сценария.
Поскольку строка shebang начинается с символа решетки, она рассматривается как комментарий и автоматически игнорируется интерпретатором Python.
Выводы
Написание комментариев является хорошей практикой и помогает другим разработчикам, в том числе будущим самим себе, понять, что делает код. В Python все, что находится после решетки ( # ) и до конца строки, считается комментарием.
Если у вас есть какие-либо вопросы или отзывы, не стесняйтесь оставлять комментарии.
