При написании кода на 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 перед именем скрипта.
Поскольку строка шебанга начинается с символа решетки, она рассматривается как комментарий и автоматически игнорируется интерпретатором Python.
Заключение
Написание комментариев — хорошая практика, которая помогает другим разработчикам, включая и меня самого, понимать, что делает код. В Python всё после символа решётки ( # ) и до конца строки считается комментарием.
Если у вас есть вопросы или пожелания, не стесняйтесь оставлять комментарии.
Связанные руководства