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 Гвидо ван Россум говорил: «Код гораздо чаще читается, чем пишется». Мы все это прекрасно знаем, но насколько это правда важно! Иногда разработчики забывают об этом, потому что не видят выгоды от этого именно в момент создания продукта. И зря.

Курс English For Tech course від Enlgish4IT.
Лише 7 тижнів по 20-30 хвилин щоденного навчання допоможуть вам подолати комунікативні бар'єри. Отримайте знижку 10% за промокодом ITCENG.
Дійзнайтеся більше

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

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

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

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

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

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

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

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

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

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

Курс English For Tech: Speaking&Listening від Enlgish4IT.
Після курсу ви зможете найкраще презентувати свої досягнення, обговорювати проекти та вирішувати повсякденні завдання англійською мовою. Отримайте знижку 10% за промокодом TCENG.
Дізнатись про курс
  • Добавление Unit-тестов

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

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

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

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

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

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

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

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

Онлайн-курс Frontend-разробник від Powercode academy.
Курс на якому ти напишеш свій чистий код на JavaScript, попрацюєш із різними видами верстки, а також адаптаціями проектів під будь-які екрани. .
Зарееструватися

Django REST Framework и drf-spectacular

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

  1. Максимум данных

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

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

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

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

  1. Генерация схемы для популярных клиент-генераторов
  2. Курс Frontend від Mate academy.
    Frontend розробник може легко створити сторінки вебсайту чи вебдодаток. Тому після курсу ви станете затребуваним фахівцем у сфері, що розвивається.
    Інформація про курс

Пекедж 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
  • Англійська для початківців від Englishdom.
    Для тих, хто тільки починає вивчати англійську і хоче вміти використовувати базову лексику і граматику.
    Реєстрація на курс

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

  • @extend_schema_serializer

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

  • extensions

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

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

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

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

Курс English For IT: Communication від Enlgish4IT.
Почни легко працювати та спілкуватися з мультикультурними командами та міжнародними клієнтами. Отримайте знижку 10% за промокодом ITCENG.
Інформація про курс

Это даже не нужно использовать в сеттингах 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.

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

Еще есть респонсы с кодами по каждому ответу. К примеру, с кодом 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-код…

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

Курс "Web design" від Web-academy.
Швидкий початок кар'єри у сфері IT! Опануйте професію веб-дизайнера — почніть самостійно керувати своїм часом й отримувати високий дохід вже за 9 тижнів.
Дізнатися більше

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

Курс Frontend від Mate academy.
Frontend розробник може легко створити сторінки вебсайту чи вебдодаток. Тому після курсу ви станете затребуваним фахівцем у сфері, що розвивається.
Інформація про курс

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

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

PHP Developer в ScrumLaunch
Всего просмотровВсего просмотров
2229
#1
Всего просмотровВсего просмотров
2229
Founder at Shallwe, Python Software Engineer (Django/React)
Всего просмотровВсего просмотров
111
#2
Всего просмотровВсего просмотров
111
Career Consultant в GoIT
Всего просмотровВсего просмотров
93
#3
Всего просмотровВсего просмотров
93
CEO & Founder в Trustee
Всего просмотровВсего просмотров
92
#4
Всего просмотровВсего просмотров
92
Рейтинг блогеров

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

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

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