Комментирование кода Python

Программирование отражает ваш образ мышления, чтобы описать отдельные шаги, которые вы предприняли для решения проблемы с помощью компьютера. Комментирование вашего кода помогает объяснить ваш мыслительный процесс и помогает вам и другим позже понять цель вашего кода. Это позволяет вам легче находить ошибки, исправлять их, улучшать код позже, а также повторно использовать его в других приложениях.

Комментирование важно для всех видов проектов, независимо от того, маленькие они, средние или довольно крупные. Это важная часть вашего рабочего процесса и считается хорошей практикой для разработчиков. Без комментариев все может запутаться очень быстро. В этой статье мы объясним различные методы комментирования, поддерживаемые Python, и то, как его можно использовать для автоматического создания документации для вашего кода с помощью так называемых строк документации на уровне модуля.

Хорошие и плохие комментарии

Какими бы важными ни были комментарии, все же можно писать плохие комментарии. Они всегда должны быть краткими, конкретными и иметь информативную ценность.

Например, это довольно бесполезный комментарий:

 b = 56 # assigning ba 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] 
 # -----------------------------------------------------------

Документальные комментарии

Python имеет встроенную концепцию, называемую docstrings , которая является отличным способом связать написанную вами документацию с модулями, функциями, классами и методами Python. Строка документации добавляется как комментарий прямо под заголовком функции, модуля или объекта и описывает, что делает функция, модуль или объект. Ожидается, что будут соблюдаться следующие правила:

Строка документации - это либо однострочный, либо многострочный комментарий. В последнем случае первая строка представляет собой краткое описание, а после первой строки следует пустая строка.
Строку документации начинайте с заглавной буквы и заканчивайте точкой.

Это простой пример того, как это выглядит:

 def add(value1, value2): 
 """Calculate the sum of value1 and value2.""" 
 return value1 + value2

В интерактивной справочной системе Python __doc__ документации становится доступной через атрибут __doc__.

 >>> print add.__doc__ 
 Calculate the sum of value1 and value2.

Существует ряд инструментов, которые автоматически создают документацию из строк документации, например Doxygen , PyDoc , pdoc и расширение autodoc для Sphinx. Мы объясним вам, как с ними работать, в следующей статье.

Заключение

Написание правильных комментариев в коде Python не так уж сложно, и вам просто нужна сила выносливости. Это помогает всем нам, кто пытается понять ваш код, включая вас самих, когда вы вернетесь к своему коду позже. Мы надеемся, что совет, который мы вам здесь дали, облегчит вам создание более качественных комментариев и документации в вашем коде.

Благодарности

Автор благодарит Золеку Хофманн за ее критические комментарии при подготовке статьи.