Введение в тему
Язык программирования – это что-то среднее между человеческим языком (естественным) и языком машин (бинарным). Именно поэтому нам, людям, понимать код не так просто, как привычную речь. Из-за этого иногда так сложно разобраться в программах, написанных другими людьми или самим собой, но когда-то давно. Для того, чтоб облегчить понимание кода, во многих языках программирования введён такой инструмент, как комментарии. В том числе, можно писать комментарии в Python.
Комментарии – это неисполняемые части кода на естественном языке (чаще всего на английском, но могут быть и на русском). Для их использования определён специальный синтаксис, который мы разберём в этом уроке. Комментарий python может быть однострочным и многострочным.
Использовать комментарии python считается хорошим подходом к программированию. Они помогают проводить код-ревью, реверс инжиниринг, рефакторинг, создавать документацию. Используются не только программистами, но и тестировщиками.
Писать комментарии лучше в процессе кодирования, а не после: Вы можете забыть какую-то подробность, либо отложить это в «далёкий ящик» и увеличить тем самым технический долг.
Писать в комментариях лучше всего не о том, как работает данный участок кода, а о том почему выбран именно данный подход (алгоритм, технология, и т. д.).
Если проект маленький – это вовсе не означает, что не надо его комментировать. Так как понять свой же код, спустя долгое время, бывает совсем не просто, пожалейте себя же будущего. Запомните: любой программист тратит гораздо больше времени на чтение кода, чем на само кодирование!
Комментирование — это важная часть работы программиста и правило хорошего тона. В этом уроке Вы узнаете о различных Python comments и о так называемых строках документации.
Однострочные комментарии в python
Для написания комментариев в Питоне используется символа хеша #. Комментарий начинается с этого символа и продолжается до конца строки.
Пример комментария из «боевого» кода, модуль ctypes стандартной библиотеки:
…
class c_void_p(_SimpleCData):
_type_ = "P"
c_voidp = c_void_p # backwards compatibility (to a bug)
_check_size(c_void_p)
…
Однако, если хеш-символ является часть строкового значения, интерпретатор Пайтона не станет считать комментарием то, что идёт после него.
>>>'qwerty' # комментарий
'qwerty'
>>>'qwerty # комментарий'
'qwerty # комментарий'
В первой строке мы записали строковое значение, обрамлённое одинарными кавычками, затем хеш и текст комментария. Во второй строке Пайтон выводит строковое значение, а комментарий игнорирует. В третьей строке мы заключаем строковое значение, хеш и текст комментария в кавычки. Как видно из четвёртой строки, интерпретатор теперь расценивает как строковое значение и то, что идёт после хеша.
Однострочные комментарии можно написать двумя способами: в отдельной строке или в строке с кодом.
# комментарий в отдельной строке
pass # комментарий в строке с кодом
В Пайтоне чаще всего применяют комментарии в отдельной строке. Это связанно с тем, что PEP8 (руководство по стилю для кода Python 3) рекомендует использовать строки длинной менее 80 символов. PyCharm (самая популярная среда разработки) рекомендует до 140 символов. Такие ограничения введены для улучшения читаемости кода. Так вот, если писать комментарий в той же строке, что и код, то он скорее всего превысит рекомендуемую ширину строки.
Итого:
— Если строка с кодом короткая и комментарий короткий – пишем их в одной строке.
— Если строка с кодом и комментарием длиннее удобочитаемой ширины, переносим комментарий на новую строку.
— Если комментарий длиннее удобочитаемой ширины, разбиваем его на несколько строк.
Многострочные комментарии в python
В Python, как и во многих других языках программирования, часто используются многострочные комментарии. Кроме пояснений к коду в них может указываться:
— информация о проекте
— назначении файла
— лицензии на программное обеспечение
— авторство
— версия
— контактная информация
— год публикации
— какие-то общие рассуждения, которые автор посчитал важными
— и т. д.
Стандартным способом создать многострочный комментарий является представление такого комментария как несколько однострочных, каждый на новой строке. В начале каждой строки ставится символ решетки:
# На этой строке начинается
# многострочный комментарий
# и продолжатся на следующей.
Этот способ не всегда удобен, так как с каждой новой строкой приходится печатать символ «#».
Есть и другой, более простой способ, предназначенный для создания, но его можно использовать и для многострочных комментариев. Мы не рекомендуем им пользоваться, так как он предназначен для других целей.
В этом варианте многострочный комментарий обрамляется тремя двойными кавычками, а хеш-символы не используются:
"""
На этой строке начинается
многострочный комментарий
и продолжатся на следующей.
"""
Docstring в python
Отрывок листинга модуля concurrent стандартной библиотеки Python:
...
"""Implements ProcessPoolExecutor.
The following diagram and text describe the data-flow through the system:
|======================= In-process =====================|== Out-of-process ==|
+----------+ +----------+ +--------+ +-----------+ +---------+
| | => | Work Ids | | | | Call Q | | Process |
| | +----------+ | | +-----------+ | Pool |
| | | ... | | | | ... | +---------+
| | | 6 | => | | => | 5, call() | => | |
| | | 7 | | | | ... | | |
| Process | | ... | | Local | +-----------+ | Process |
| Pool | +----------+ | Worker | | #1..n |
| Executor | | Thread | | |
| | +----------- + | | +-----------+ | |
| | <=> | Work Items | <=> | | <= | Result Q | <= | |
| | +------------+ | | +-----------+ | |
| | | 6: call() | | | | ... | | |
| | | future | | | | 4, result | | |
| | | ... | | | | 3, except | | |
+----------+ +------------+ +--------+ +-----------+ +---------+
Executor.submit() called:
...
В Python существует прекрасный способ предоставления документации для логически обособленных частей программы. Docstring должны быть определены сразу после объявления функции, метода или класса, либо в начале модуля. Этот инструмент широко применяется – стандартная библиотека тому подтверждение. Можно сказать, что модуль, не имеющий строк документации, не может считаться готовым к релизу. Согласно PEP 8 (Python Enhancement Proposal), в Python docstring необходимо использовать для каждого создаваемого блока кода в качестве поясняющей конструкции.
Строка документа добавляется в качестве комментария заголовком функции, модуля или метода и описывает их действия. Согласно общепринятым нормам ожидается, что:
— Первая строка это лаконичное описание блока.
— Первая строка начинается с Заглавной буквы.
— Первая строка заканчивается точкой.
— Если строка документа состоит из нескольких строк, то вторая строка должна быть пустой.
— Начиная с третьей строки идёт более детальное описание блока (его сторонние эффекты, описание структуры, интерфейс и т. д.)
Есть несколько инструментов, которые генерируют документацию из строк документации в автоматическом режиме. Назовём некоторые из них: расширение autodoc для Sphinx, PyDoc, Doxygen, pdoc.
Как задать docstring в python
Docstring необходимо помещать на следующей строке после определения класса, метода, функции или модуля, заключая текст в тройные кавычки.
def foo():
"""Функция для примера.
Эта функция ничего не делает."""
pass
В этом коде Вы можете видеть простейший пример строк документации. Первая строка коротко описывает функцию, вторая отделяет дальнейший текст, а, начиная с третьей строки, идёт пояснение каких-то деталей.
В чём отличие между комментарием и docstring
Комментарии полностью игнорируются интерпретатором Питона. С docstring всё иначе: они обрабатываются и помещаются в полученный байт-код. Во время выполнения программы строки документации можно вывести на экран с помощью функции help() или получить к ним доступ используя метод __doc__.
Какими должны быть комментарии
Как говорилось выше, комментарии в Python очень важны. Их использование тесно связано с понятием «чистый код». Вот несколько советов о том, какими должны и какими не должны быть комментарии:
— Комментарий должен быть содержательным.
— Описывайте не «как», а «почему». Важно объяснить свой выбор в пользу того или иного пути решения поставленной задачи.
— Описывайте неочевидные места программы, но стремитесь к тому, чтоб таких мест не было.
— Избегайте длинных комментариев. Информацию из таких комментариев лучше перенести в docstring.
— Избегайте таких комментариев, которые не содержат полезной информации.
— Используйте одинаковый стиль оформления комментариев во всём проекте.
Помните, что комментарии достаточно сложно поддерживать в актуальном состоянии. Всё в порядке, когда это маленький проект без горящих сроков. Но, представьте ситуацию, когда в проекте участвует сотня программистов. Один программист пишет строку кода и сразу же её комментирует. Затем он увольняется. Вдруг, через час после релиза, где-то в этом месте всплывает баг. Уже другой программист берётся фиксить этот баг и, в результате, полностью переписывает функцию, но, так как дедлайн, да и вообще лень, он оставляет старые комментарии – всё равно они не исполняются интерпретатором.
Представили? А теперь представьте, что Вы приходите работать в эту компанию, начинаете вникать в проект и читаете именно эти строки кода. Код об одном, комментарии о другом (о старом коде). Здесь они не только не помогают, но и сбивают с толку и лучше бы их вообще не было.
Идеальный код должен быть понятен на столько, чтобы не было необходимости в комментариях. Это достигается правильным выбором имён переменных, функций, классов и прочих сущностей. Но, это в идеальном мире. В нашем же мире совсем без комментариев не обойтись.
