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

Документирование кода на ранних этапах разработки имеет гораздо большее значение, чем может показаться на первый взгляд. Эта тема также связана с добавлением полезных комментариев к коду. Когда вы погружаетесь в разработку программы, вы можете неосознанно присвоить своим переменным и функциям весьма странные и непонятные названия. Таким образом, через некоторое время, вернувшись к коду, вы потратите огромное количество времени, пытаясь разобраться, что к чему.

Содержание статьи

Создавая самодокументирующийся код (то есть используя информативные имена) и добавляя комментарии, вы сделаете программу более читабельной для себя и для всех остальных, кто может её использовать. Это также облегчит обновление и рефакторинг кода!


Есть вопросы по Python?

На нашем форуме вы можете задать любой вопрос и получить ответ от всего нашего сообщества!

Telegram Чат & Канал

Вступите в наш дружный чат по Python и начните общение с единомышленниками! Станьте частью большого сообщества!

Паблик VK

Одно из самых больших сообществ по Python в социальной сети ВК. Видео уроки и книги для вас!

В данной статье вы познакомитесь со следующими темами:

  • Комментарии;
  • Строки документации — Docstrings;
  • PEP8 — Руководство по написанию кода;
  • Другие полезные инструменты для документирования вашего кода.

Давайте начнем с комментариев.

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

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

Тем не менее, комментарии все равно рекомендуется использовать. Они особенно полезны для сложного кода, который нелегко понять с первого взгляда. В зависимости от компании, в которой вы работаете, вы также можете использовать комментарии для документирования багов. Например, если вы исправили ошибку, вы можете добавить комментарий, объясняющий, в чем именно она заключалась.

В Python комментарии создаются с помощью знака #, за которым следует описательный текст.

Пример плохого комментария в Python:

В этом примере комментарий не добавляет полезной информации и не объясняет последующий код. Такие комментарии следует избегать.

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

Вы также можете создавать комментарии на строке с кодом:

Здесь вы присваиваете переменной x значение 10 и добавляете комментарий, поясняющий это действие. Это полезно, когда необходимо объяснить конкретную строку кода. Если вы назвали свою переменную логически и интуитивно понятно, то, скорее всего, комментарий не понадобится.

Как закомментировать и раскомментировать строки кода

В процессе разработки вы часто будете сталкиваться с понятием «закомментированный код«. Это практика добавления символа # в начале строки кода, чтобы временно отключить её выполнение без удаления.

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

Например, у вас может быть следующая строка кода:

Если вы хотите закомментировать её, это можно сделать следующим образом:

Закомментировать код полезно, когда вы пробуете различные решения, но не хотите удалять предыдущие варианты программы. Python будет игнорировать закомментированный код, позволяя вам экспериментировать с разными подходами.

Большинство редакторов кода IDE и текстовых редакторов предоставляют возможность выделять несколько строк и закомментировать весь блок кода.


Горячие клавиши для комментирования куска кода: (выделить нужный участок кода) + Ctrl + /

Многострочные комментарии в Python

Некоторые языки программирования, например C++, предоставляют возможность создания многострочных комментариев. В Python для создания многострочных комментариев можно использовать тройные кавычки.

Пример многострочного комментария на Python:

При использовании строк с тройными кавычками вы можете создать docstring (строки документации). В данном случае, мы уже использовали многострочные комментарии для функции test().

Давайте разберемся, что такое docstring и как его использовать!


Для чего используется docstring?

В Python существует концепция PEP (Python Enhancement Proposal). PEP — это предложения или новые возможности для языка Python, которые обсуждаются и согласовываются руководящим советом Python.

PEP 257 описывает соглашения о docstring. Вкратце, docstring — это строковый литерал, который должен находиться сразу после определения названия модуля, функции, класса или метода.

Docstring создается с помощью тройных двойных кавычек.

Пример:

В Python docstring игнорируются во время выполнения кода. Однако, когда вы добавляете docstring к модулю, функции и так далее, эта строка становится специальным атрибутом, доступным через __doc__.

Пример использования docstring в классе:

Результат выполнения:

Docstring можно использовать как для однострочных, так и для многострочных строк.

Пример однострочной строки:

Однострочный docstring — это простая строка текста.

Пример использования docstring в функции:

В этом примере показано, как добавить docstring к функции. Хороший docstring описывает, что должна делать функция.

На заметку: Хотя тройные двойные кавычки являются рекомендуемым стандартом, тройные одинарные кавычки, а также одиночные двойные или одинарные кавычки также работают. Однако одиночные кавычки подходят только для однострочных строк.

Теперь давайте рассмотрим создание программы в соответствии с руководством по написанию кода на Python.

PEP 8 — руководство по написанию кода на Python

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

Руководство по написанию кода Python, известное как PEP8, было создано в 2001 году и с тех пор несколько раз обновлялось. В нем описаны соглашения по программированию на языке Python.


Если вы планируете активно использовать Python, вам стоит ознакомиться с этим руководством. Оно поможет вам писать более качественный и читаемый код. Кроме того, если вы хотите внести вклад в развитие самого языка Python, ваш код должен соответствовать стилю руководства. Следование PEP8 сделает ваш код более понятным для вас и других разработчиков, которые будут с ним работать в будущем.

Однако запомнить все правила может быть непросто. К счастью, существуют инструменты, которые могут помочь!

Полезные инструменты для документирования вашего кода

Существует множество инструментов, которые можно использовать для написания качественного кода. Вот несколько из них:

  • pycodestyle — проверяет соответствие вашего кода стандарту PEP8;
  • Pylint — инструмент для статического анализа кода, который находит общие проблемы;
  • PyFlakes — еще один инструмент для статического анализа кода;
  • flake8 — объединяет возможности PyFlakes, pycodestyle и McCabe;
  • Black — форматировщик кода, который автоматически форматирует ваш код согласно стандарту PEP8.

Вы можете использовать эти инструменты для поиска проблемных мест в вашем коде. Pylint, PyFlakes и flake8 особенно полезны для выявления ошибок и несоответствий. Black пригодится, если вы работаете в команде и хотите, чтобы код каждого разработчика был оформлен в едином стиле. Рекомендуется добавить Black в свой список инструментов для форматирования кода.

Более продвинутые IDE для Python, такие как PyCharm, WingIDE и VS Code, предоставляют встроенные проверки кода в режиме реального времени. Эти IDE автоматически выявляют многие проблемы, которые исправляют упомянутые инструменты. Попробуйте различные IDE, чтобы выбрать ту, которая лучше всего подходит вам.

Подведем итоги

В Python существует несколько способов документирования кода. Вы можете использовать комментарии для пояснения одной или нескольких строк кода, однако их следует использовать умеренно и по мере необходимости. Также вы можете использовать docstring для документирования модулей, функций, методов и классов.

Рекомендуется ознакомиться с руководством по программированию на Python — PEP8. Это поможет вам понять принципы хорошего программирования на Python. Существуют и другие руководства по стилю написания кода на Python, такие как руководство от Google или руководство от NumPy. Ознакомление с различными стилями может помочь вам разработать свой собственный хороший стиль программирования.

Мы также рассмотрели несколько инструментов, которые можно использовать для улучшения вашего кода. Если у вас есть время, рекомендую ознакомиться с PyFlakes или flake8, так как они могут помочь найти общие проблемы в вашем коде.