ru:https://highload.today/blogs/zachem-i-kak-dokumentirovat-kod-na-python-osnovnye-shagi-i-sovety-razrabotchika/ ua:https://highload.today/uk/blogs/navishho-i-yak-dokumentuvati-kod-na-python-osnovni-kroki-ta-poradi-rozrobnika/
logo
Опыт      19/08/2022

Зачем и как документировать код на Python: основные шаги и советы разработчика

Демід Седих BLOG

Python Developer в NIX

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

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

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

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

Для конкретизации требований нужно пообщаться с продакт-командой, спросить по каждому пункту реквайроментов, уточнить разные детали. Именно так у вас появится основа для написания кода.

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

Когда нужно начинать комментировать код

Самое эффективное и простое документирование кода — во время его имплементации.

Когда у вас сформированы более или менее четкие бизнес-реквайроменты и вы переходите к созданию фактически Proof of Concept, сразу начинайте документировать код.

Ведь вы только что обсуждали с продакт-командой детали проекта и создавали фрагменты будущей реализации. Сложившееся понимание продукта легче добавлять к коду. Так уже на ранних стадиях проекта вы сделаете его понятным всем привлеченным разработчикам.

Отец Python Гвидо ван Россум говорил: «Код гораздо чаще читается, чем пишется». Мы все это прекрасно знаем, но насколько это правда важно! Иногда разработчики забывают об этом, потому что не видят выгоды от этого именно в момент создания продукта. И зря.

AWS для початківців.
Навчіться працювати з cloud-native системами та побудуйте власний застосунок для зберігання даних у системі AWS.
Дійзнайтеся більше

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

Основные шаги в документации кода

  • Добавление док-стрингов

Это можно делать в функциях, классах, методах, переменных. Так вы можете объяснить, что выполняют определенные элементы кода. Сделать это можно по-разному. Я, например, после получения документации и комментариев от продакт-команды часто добавляю их фрагменты в модели или в классы — так удобнее.

  • Комментарии к любым непонятным частям кода

Иногда определенный фрагмент может отрабатывать только одну маленькую бизнес-логику, незнакомую стороннему разработчику. Комментарии помогут понять, почему все сделано именно так. Эти пояснения следует вписывать сразу после кода.

  • Аннотации типов

Помогает сделать код более ясным и лаконичным. При знакомстве с функцией с задекларированными типами становится очевидным, что она представляет собой и какие типы аргументов следует добавлять.

  • Описание бизнес-логики

Писать следует не только о том, что делает конкретная функция, но и о том, как она работает в реальном флоу-проекте, какую часть выполняет эта функция в существующем флоу.

  • Добавление Unit-тестов

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

И еще один совет: если вы используете Django-аппликации и Django REST Framework, то обязательно применяйте Swagger .

Подробнее об этом я расскажу чуть позже.

Перейдем к примерам

Многие разработчики не знают, где искать методы документирования кода, style guide и best practices по этой теме. Google поможет! Вбиваем в поисковик google python style guide example и получаем четкие рекомендации.

Один из примеров документирования кода можно увидеть на иллюстрации ниже. В начале модуля имеется multiline string. Первая строка — это краткое описание самого документа. Затем — подробное объяснение, примеры запуска модуля, если это скрипт, а также возможные описания атрибутов и переменных в модуле.

На следующей иллюстрации показана документация к функциям. Обратите внимание: здесь не используется инструкция типов, хотя внутри функции есть их описание. Я бы делал его именно в декларации аргументов:

А еще важно, что среди докстринг-форматов у PyCharm один именно от Google. Лично я выбрал его по умолчанию. При написании функции достаточно нажать Ctrl+Enter и получить автозаполнение в стиле Google:

Django REST Framework и drf-spectacular

И вот теперь пойдет речь о Swagger. В этом случае вам пригодится drf-spectacular. Это относительно свежий пекедж, он постоянно обновляется и обслуживается. Именно на него мы в нашей команде заменяем большинство устаревших аналогов. У drf-spectacular есть несколько основных функций, построенных вокруг трех целей:

Онлайн курс з промт інжинірингу та ефективної роботи з ШІ.
Курс-інтенсив для отримання навичок роботи з ChatGPT та іншими інструментами ШІ для професійних та особистих задач, котрі допоможуть як новачку, так і професіоналу.
Записатися на курс
  1. Максимум данных

Благодаря drf-spectacular можно получать как можно больше информации из имеющихся функций и классов. Правда, это касается только Django REST Framework.

  1. Добавление функционала при кастомизации

Имея drf-spectacular, у вас есть дополнительные возможности для более элегантного и расширенного документирования. Очень полезно для кастомизированных элементов, например сериалайзера. Если вы изменяете его, допустим, из-за использования метода to representation, то drf-spectacular может не подхватить эти изменения автоматически. Тогда возникает ошибка об отсутствии полей этого сериалайзера. В таком случае вы должны задекларировать в API view или ViewSet другой сериалайзер, а тот, что с методом to representation, использовать именно в коде:

Благодаря этому у ViewSet не будет сериалайзера с методом to representation. Вы сможете декларировать все филды, которые используете в этом методе для возврата данных:

  1. Генерация схемы для популярных клиент-генераторов

Пекедж drf-spectacular использует все законы OpenAPI. Это набор правил, описывающих создание любого RESTful-сервиса. Для этого используется Swagger UI.

Что касается технических особенностей drf-spectacular, то он поддерживает многие пекеджи, перечень которых приведен на картинке ниже. Также он требует Python не ранее версии 3.6 и одной из нескольких версий Django и Django REST Framework.

Полезный функционал drf-spectacular

  • @extend_schema

Этот декоратор позволяет многое кастомизировать в эндпоинтах. Представим листинг фильмов, где вы добавляете в методе get queryset определенные фильтры. Если клиент придаст в query-параметрах дополнительные значения, например для выборки снятых после 1986 года фильмов, то drf-spectacular не найдет информацию в коде о возможности такой фильтрации. Но через аргумент вы можете добавить необходимые API параметры из этого эндпоинта. Можно указать название параметра, тип, локации, описания, примеры и формат использования этого параметра. К тому же здесь есть description для документирования методов из ViewSet или View.

  • @extend_schema_view

По большей части при наличии ViewSet не нужно изменять метод list, как это сделано в предыдущем примере. Вы просто вызываете этот метод сверху строчки. Однако это можно сделать другим способом — с использованием extend_schema_view, которая будет крепиться к ViewSet. Так можно указывать довод, какой метод нужно декорировать. По сути, это тоже самое, но первый пример касался метода, а этот — самого View.

  • @extend_schema_field

Этот функционал требуется для кастомизации филдов сериалайзера. Сам по себе drf-spectacular не знает, какой тип объекта возвращается и какие манипуляции есть в этом методе. Но мы можем декорировать сериалайзер метод field, скажем, для указания выводимого типа следующим образом:

  • @extend_schema_serializer

Позволяет запечатлеть филды и добавить экземплы. В примере я это не использовал, но функционал считается основным для drf-spectacular.

  • extensions

При модификациях аутентификации и авторизации нужно добавлять к проекту extensions. Таким образом drf-spectacular увидит изменения в этих процессах, что мы поговорим далее.

Модификация аутентификации

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

В приведенном проекте extension аутентификации построено следующее: есть модифицированная и кастомизированная JSONWebTokenAuthentication, указано, как выглядит аутентификация.

Это даже не нужно использовать в сеттингах drf-spectacular. Когда Python-интерпретатор «видит» класс с подражанием OpenAPI от extension, он заменяет базовый по умолчанию extension на задекларированный в коде.

Подключение drf-spectacular

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

Перед вами API календаря проекта. Здесь есть несколько эндпоинтов, среди которых, например, event-exclusions. В нем собран полный листинг всех exclusions этого типа.

В первом пункте есть документация с описанием бизнес-логики. Каждый event-exclusion — это сущность, содержащая функционал и управляющая тем, как могут быть просмотрены вижуал-ивенты. Указано и то, что каждый event-exclusion подключен к конкретному вижуал-ивенту.

Также есть параметры, которые клиент может добавлять в Query для получения конкретных event-exclusions. К примеру, можно найти event-exclusions, где закенселен Event Template.

Еще есть респонсы с кодами по каждому ответу. К примеру, с кодом 200 приходит ответ следующего формата: 

Так выглядит респонс сериалайзера EventExclusionViewSet. При этом внутри ViewSet нет метода list. Поэтому я задекорировал extend_schema_view, добавил ей аргумент list и функцию extend_schema, которая работает так же, как я это сделал бы до метода.

Далее виден тот же параметр is_cancelled, который описан выше. У него есть описание, тип, локация и пример. Это все было сделано при наличии метода get_queryset, в котором выполняется фильтрация queryset в соответствии со входными query-параметрами.

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

Мне встречалось немало плохо продуманных с этой точки зрения Django-проектов. Иногда там было столько непонятного! Например, однажды я нашел в файле serializer.py кастомизированные сериалайзеры с кастомными методами типа retrieve, вызываемыми в самом View. Все работает, как при to representation, но без использования стиля Django REST Framework. Специалист, хорошо знакомый с Django и DRF, вообще не понимает причины такой логики. Это подобно тому, как писать в Django-приложении FastAPI-код…

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

If you have found a spelling error, please, notify us by selecting that text and pressing Ctrl+Enter.

Data Engineering.
Курс для тих, хто хоче навести лад в архітектурі даних та опанувати ключові інструменти дата-інженера на практиці.
Реєстрація на курс

Этот материал – не редакционный, это – личное мнение его автора. Редакция может не разделять это мнение.

Топ-5 самых популярных блогеров февраля

Всего просмотровВсего просмотров
229
#1
Всего просмотровВсего просмотров
229
Всего просмотровВсего просмотров
209
#2
Всего просмотровВсего просмотров
209
QA в CodeGeeks Solutions
Всего просмотровВсего просмотров
156
#3
Всего просмотровВсего просмотров
156
Senior Project Manager at Nemesis
Всего просмотровВсего просмотров
99
#4
Всего просмотровВсего просмотров
99
Software Architect at Devlify
Всего просмотровВсего просмотров
95
#5
Всего просмотровВсего просмотров
95
Рейтинг блогеров

Ваша жалоба отправлена модератору

Сообщить об опечатке

Текст, который будет отправлен нашим редакторам: