Документирование кода на ранних этапах разработки имеет гораздо большее значение, чем может показаться на первый взгляд. Эта тема также связана с добавлением полезных комментариев к коду. Когда вы погружаетесь в разработку программы, вы можете неосознанно присвоить своим переменным и функциям весьма странные и непонятные названия. Таким образом, через некоторое время, вернувшись к коду, вы потратите огромное количество времени, пытаясь разобраться, что к чему.
Содержание статьи
- Комментарии в коде
- Как закомментировать и раскомментировать строки кода
- Многострочные комментарии
- Для чего используется docstring?
- PEP 8 — руководство по написанию кода на Python
- Полезные инструменты для документирования вашего кода
- Подведем итоги
- Вопросы для проверки
Создавая самодокументирующийся код (то есть используя информативные имена) и добавляя комментарии, вы сделаете программу более читабельной для себя и для всех остальных, кто может её использовать. Это также облегчит обновление и рефакторинг кода!
В данной статье вы познакомитесь со следующими темами:
- Комментарии;
- Строки документации — Docstrings;
- PEP8 — Руководство по написанию кода;
- Другие полезные инструменты для документирования вашего кода.
Давайте начнем с комментариев.
Комментарии в коде на Python
Комментарии — это подсказки, предназначенные для разработчиков, а не для компьютера. По сути, комментарий — это заметка, объясняющая, что происходит в определенной части кода. Они используются для пояснения, почему вы что-то сделали или как работает тот или иной фрагмент кода. Когда вы только начинаете программировать, полезно оставлять много комментариев, к которым можно будет потом вернуться. По мере улучшения навыков именования функций и переменных вы поймете, что многие комментарии становятся ненужными.
Тем не менее, комментарии все равно рекомендуется использовать. Они особенно полезны для сложного кода, который нелегко понять с первого взгляда. В зависимости от компании, в которой вы работаете, вы также можете использовать комментарии для документирования багов. Например, если вы исправили ошибку, вы можете добавить комментарий, объясняющий, в чем именно она заключалась.
В Python комментарии создаются с помощью знака
#, за которым следует описательный текст.
Пример плохого комментария в Python:
|
1 2 |
# Это плохой комментарий x = 10 |
В этом примере комментарий не добавляет полезной информации и не объясняет последующий код. Такие комментарии следует избегать.
Хорошие комментарии должны объяснять и описывать последующий код, его цели или что-то еще. Комментарии — это своего рода документация вашего кода. Если они не предоставляют никакой полезной информации, их следует удалить.
Вы также можете создавать комментарии на строке с кодом:
|
1 |
x = 10 # Присваиваем значение 10 переменной x |
Здесь вы присваиваете переменной x значение 10 и добавляете комментарий, поясняющий это действие. Это полезно, когда необходимо объяснить конкретную строку кода. Если вы назвали свою переменную логически и интуитивно понятно, то, скорее всего, комментарий не понадобится.
Как закомментировать и раскомментировать строки кода
В процессе разработки вы часто будете сталкиваться с понятием «закомментированный код«. Это практика добавления символа # в начале строки кода, чтобы временно отключить её выполнение без удаления.
Например, у вас может быть следующая строка кода:
|
1 |
number_of_people = 10 |
Если вы хотите закомментировать её, это можно сделать следующим образом:
|
1 |
# number_of_people = 10 |
Закомментировать код полезно, когда вы пробуете различные решения, но не хотите удалять предыдущие варианты программы. Python будет игнорировать закомментированный код, позволяя вам экспериментировать с разными подходами.
Большинство редакторов кода IDE и текстовых редакторов предоставляют возможность выделять несколько строк и закомментировать весь блок кода.
Горячие клавиши для комментирования куска кода: (выделить нужный участок кода) + Ctrl + /
Многострочные комментарии в Python
Некоторые языки программирования, например C++, предоставляют возможность создания многострочных комментариев. В Python для создания многострочных комментариев можно использовать тройные кавычки.
Пример многострочного комментария на Python:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
'''Это многострочный комментарий''' data = 1 """Это также многострочный комментарий""" b = 3 def test(): """ Функция возвращает число. """ return 1 |
При использовании строк с тройными кавычками вы можете создать docstring (строки документации). В данном случае, мы уже использовали многострочные комментарии для функции test().
Давайте разберемся, что такое docstring и как его использовать!
Для чего используется docstring?
В Python существует концепция PEP (Python Enhancement Proposal). PEP — это предложения или новые возможности для языка Python, которые обсуждаются и согласовываются руководящим советом Python.
PEP 257 описывает соглашения о docstring. Вкратце, docstring — это строковый литерал, который должен находиться сразу после определения названия модуля, функции, класса или метода.
Docstring создается с помощью тройных двойных кавычек.
Пример:
|
1 2 3 4 |
""" Это docstring из нескольких строк """ |
В Python docstring игнорируются во время выполнения кода. Однако, когда вы добавляете docstring к модулю, функции и так далее, эта строка становится специальным атрибутом, доступным через __doc__.
Пример использования docstring в классе:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
class Dog: """ Это класс собаки. """ def bark(self): """ Собака лает из метода! """ return True animal = Dog() print(animal.__doc__) # Вывод: Это класс собаки. print(animal.bark.__doc__) # Вывод: Собака лает из метода! |
Результат выполнения:
|
1 2 |
Это класс собаки. Собака лает из метода! |
Docstring можно использовать как для однострочных, так и для многострочных строк.
Пример однострочной строки:
|
1 |
text = """Это однострочная строка""" |
Однострочный docstring — это простая строка текста.
Пример использования docstring в функции:
|
1 2 3 |
def my_function(): """Это docstring функции""" pass |
В этом примере показано, как добавить 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, так как они могут помочь найти общие проблемы в вашем коде.
Являюсь администратором нескольких порталов по обучению языков программирования Python, Golang и Kotlin. В составе небольшой команды единомышленников, мы занимаемся популяризацией языков программирования на русскоязычную аудиторию. Большая часть статей была адаптирована нами на русский язык и распространяется бесплатно.
E-mail: vasile.buldumac@ati.utm.md
Образование
Universitatea Tehnică a Moldovei (utm.md)
- 2014 — 2018 Технический Университет Молдовы, ИТ-Инженер. Тема дипломной работы «Автоматизация покупки и продажи криптовалюты используя технический анализ»
- 2018 — 2020 Технический Университет Молдовы, Магистр, Магистерская диссертация «Идентификация человека в киберпространстве по фотографии лица»