Введение
При написании кода на 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."Комментарии должны быть на том же уровне отступа, что и приведенный ниже код:
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 все, что следует за знаком решетки ( # ) и до конца строки, считается комментарием.
