Автор оригинала: Frank Hofmann.
Комментирование кода Python
Программирование отражает ваш образ мышления, чтобы описать отдельные шаги, которые вы предприняли, чтобы решить проблему с помощью компьютера. Комментирование кода помогает объяснить ваш мыслительный процесс, а также помогает вам и другим понять позже намерение вашего кода. Это позволяет вам легче находить ошибки, исправлять их, впоследствии улучшать код и повторно использовать его в других приложениях.
Комментирование важно для всех видов проектов, независимо от того, являются ли они малыми, средними или довольно крупными. Это неотъемлемая часть вашего рабочего процесса, и это считается хорошей практикой для разработчиков. Без комментариев все может запутаться очень быстро. В этой статье мы расскажем о различных методах комментирования, поддерживаемых Python, и о том, как его можно использовать для автоматического создания документации для вашего кода с помощью так называемых док-строк уровня модуля.
Хорошие и плохие комментарии
Как бы ни были важны комментарии, все же можно писать плохие комментарии. Они всегда должны быть короткими, прямолинейными и иметь информативную ценность.
Например, это довольно бесполезный комментарий:
b = 56 # assigning b a value of 56
Следующий пример показывает более полезный комментарий, вместо этого, и идет вместе с указанием переменных очевидных имен:
salestax10 = 1.10 # defining a sales tax of 10% salestax20 = 1.20 # defining a sales tax of 20%
Существует бесконечное множество других сценариев, которые требуют комментариев. Это только один пример. Хорошим эмпирическим правилом было бы добавлять комментарии для любой строки кода (например, для понимания списка) или раздела кода, назначение которого не очевидно. Это очень субъективно, и на самом деле это навык, которому нужно научиться.
Типы комментариев
Комментарий в Python начинается с хэш-символа # и продолжается до конца физической строки. Однако хэш-символ в строковом значении не рассматривается как комментарий. Если быть точным, комментарий может быть написан тремя способами – полностью на своей собственной строке, рядом с инструкцией кода и в виде многострочного блока комментариев.
В следующих разделах я опишу каждый тип комментариев.
Однострочные комментарии
Такой комментарий начинается с хэш-символа ( # ) и сопровождается текстом, содержащим дополнительные пояснения.
# defining the post code postCode = 75000
Вы также можете написать комментарий рядом с инструкцией кода. Следующий пример показывает, что:
# define the general structure of the product with default values
product = {
"productId": 0, # product reference id, default: 0
"description": "", # item description, default: empty
"categoryId": 0, # item category, default: 0
"price": 0.00 # price, default: 0.00
}
Руководство по стилю кода Python ( PEP8 ) рекомендует не более 79 символов в строке. На практике 70 или 72 символа в строке легче читать, и поэтому рекомендуется. Если ваш комментарий приближается к этой длине или превышает ее, то вы захотите распространить его на несколько строк.
Многострочные комментарии
Как уже упоминалось выше, весь блок комментариев также понимается Python. Эти комментарии служат встроенной документацией для других, читающих ваш код, и обычно объясняют вещи более подробно.
Технически Python не имеет явной поддержки многострочных комментариев, поэтому некоторые считают следующие параметры обходным путем, но все же работают с целью многострочных комментариев.
Версия 1 объединяет однострочные комментарии следующим образом:
# LinuxThingy version 1.6.5 # # Parameters: # # -t (--text): show the text interface # -h (--help): display this help
Версия 2 проще, чем версия 1. Первоначально он предназначался для создания документации (подробнее об этом читайте ниже), но также может использоваться для многострочных комментариев.
""" LinuxThingy version 1.6.5 Parameters: -t (--text): show the text interface -h (--help): display this help """
Обратите внимание, что последняя версия должна быть заключена в специальные кавычки ( """ ) для работы, а не хэш-символы.
Обычная Практика
Довольно часто файл Python начинается с нескольких строк комментариев. В этих строках содержится информация о проекте, назначении файла, программисте, который его разработал или работал над ним, и лицензии на программное обеспечение, которая используется для кода.
Этот фрагмент взят из одного из примеров, которые я использую в учебных целях. Комментарий начинается с описания, а затем следует уведомление об авторских правах с моим именем и годом публикации кода. Ниже вы увидите, что код лицензирован под лицензией GNU Public License ( GPL ). Чтобы связаться со мной, мой адрес электронной почты тоже добавлен туда.
# ----------------------------------------------------------- # demonstrates how to write ms excel files using python-openpyxl # # (C) 2015 Frank Hofmann, Berlin, Germany # Released under GNU Public License (GPL) # email [email protected] # -----------------------------------------------------------
Комментарии к Docstring
Python имеет встроенную концепцию под названием docstrings , которая является отличным способом связать написанную вами документацию с модулями, функциями, классами и методами Python. Строка документа добавляется в качестве комментария прямо под заголовком функции, модуля или объекта и описывает, что делает эта функция, модуль или объект. Ожидается, что он будет следовать этим правилам:
Строка документа-это либо однострочный, либо многострочный комментарий. В последнем случае первая строка представляет собой краткое описание, а после первой строки следует пустая строка.
Начинайте строку с заглавной буквы и заканчивайте точкой.
Это основной пример того, как это выглядит:
def add(value1, value2):
"""Calculate the sum of value1 and value2."""
return value1 + value2
В интерактивной справочной системе Python строка docstring становится доступной через атрибут __doc__ .
>>> print add.__doc__ Calculate the sum of value1 and value2.
Существует ряд инструментов, которые автоматически генерируют документацию из строк документов, таких как Doxygen , PyDoc , pydoc и расширение autodoc для Sphinx. Мы объясним вам, как с ними работать, в следующей статье.
Вывод
Написание правильных комментариев в вашем коде Python не так уж сложно, и вам просто нужна сила выносливости. Это помогает всем нам, кто пытается понять ваш код, включая вас самих, когда вы вернетесь к своему коду позже. Мы надеемся, что советы, которые мы дали вам здесь, облегчат вам создание лучших комментариев и документации в вашем коде.
Признание
Автор хотел бы поблагодарить Золеку Хофманн за ее критические замечания при подготовке этой статьи.