Почему так трудно документировать код?
Код программы, написанный на Java, C ++ или любом другом языке, сложно документировать в частности потому, что технические писатели часто не владеют языком программирования. Но даже для писателей или разработчиков, свободно владеющих языком, эта задача может быть трудной. Отсутствует пошаговый процесс, которому надо следовать. Код часто упорядочен в нелинейном порядке, поэтому не получится просто идти построчно по нему. Существует также вопрос о том, сколько документировать, что покрывать и куда включать документацию. В целом, лучшие практики документирования кода нечеткие и неопределенные, что делает документирование кода одной из самых сложных и трудоемких задач, стоящих перед техническими авторами.
В разделе Описание и образцы кода есть упоминание о важности документирования кода. Но, учитывая важность этой темы, мы рассмотрим ее шире в этом разделе.
Свежий опыт документирования кода
Абстрактные темы хорошо подкреплять реальным опытом. Недавний проект, над которым работал автор курса — разработка логики бэкенда для голосового управления приложением Fire TV, чтобы пользователи могли сказать «Play Interstellar» (или название другого фильма), и приложение запустить этот фильм.
Когда пользователи произносят команды голосовому помощнику Alexa, Alexa интерпретирует команды и упаковывает информацию в структурированный JSON-запрос на отправку партнеру кода Lambda. Lambda, сервис AWS, обеспечивает внесерверные вычисления. Предполагается, что партнеры прослушивают входящие запросы, а затем выдают собственный код для надлежащего ответа на запросы, предположительно получая идентификатор для Instellar (в этом примере) и отправляя этот идентификатор в свое приложение Fire TV для воспроизведения.
Реализация включала в себя кодирование лямбда-функции. Чтобы помочь разработчикам, инженеры предоставили пример лямбда-функции (в Node JS), но без объяснения причин. Работая над документацией, возникла потребность пояснения логики лямбда-кода.
Лямбда-код написан на 450 строках и не очень сложен. Не зная Lambda или Node JS, пришлось много изучить, чтобы понять, что происходит в каждой строке. В подходе к документированию кода объясняются условия, которые инициировали лямбда-код для вызова в первую очередь. Затем лямбда-код был показан полностью, чтобы у пользователя был контекст. Затем код был разделен на четыре отдельных логических раздела. Под полным примером кода был представлен каждый раздел (помечая их как пояснение к разделу 1, объяснение к разделу 2 и т.д.), Пока не был пройден весь пример кода.
Такой подход был не особо хорош, но другого метода не было. Хотелось бы подробнее остановиться на каждом из раздело, а не просто делать краткие комментарии. Полученную документацию можете увидеть здесь: Шаг 3: Понимание директив Alexa и лямбда-ответов (мультимодальные устройства). Нет сомнений в том, что эта документация скоро изменится, поэтому подробностей, помимо описанного подхода, нет. Но такой подход можно рассматривать как введение в проблему документирования кода.
В целом, документирование кода, пожалуй, самый сложный аспект технического писательства, особенно для не инженеров. Ниже описаны несколько причин, почему документирование кода ставит так много проблем.
Проблема 1: Код не следует пошаговой парадигме
Код нелинейный. То, что появляется вверху (например, переменные), может не реализовываться до функций, определенных внизу. Функции, определенные внизу, могут выполняться внутри других блоков кода в середине и т.д. Порядок сборки фрагмента кода вообще неочевиден.
Основная парадигма, которой следуют большинство технических писателей, — это модель, основанная на задачах, где вы начинаете с шагов 1, 2, 3 и так далее, пока не достигнете конца задачи. Это не относится к документации по коду. Код является нелинейным по своей природе, поэтому нельзя просто начать сверху и перейти к нижней части. Могут быть лучшие практики, дополнительные методы, списки параметров, концептуальные объяснения в сочетании с другими деталями и многое другое. Стратегия документирования кода состоит в том, чтобы представить полный пример кода, за которым следуют разделы, которые объясняют различные аспекты кода. Такой подход очень отличается от процедурного подхода, обычно применяемого в технических документах.
Проблема 2: Аудитория может иметь разный технический уровень
Другой проблемой, с которой пришлось столкнулся, это понимание, что нужно объяснять, а что можно пропустить. Разбираются ли разработчики уже в обработчиках в Lambda и Node JS? Или это для них новинка?
Технический писатель должен писать в соответствии с уровнем знаний своей аудитории, даже если технические уровни разных аудиторий сильно различаются. Документация обычно либо переписывается для продвинутых разработчиков, объясняя очевидное, либо отталкивает менее опытных разработчиков, поясняя слишком много. Реализация прогрессивных моделей раскрытия информации может быть сложной. Даже если аудитория технически грамотная, она не гарантирует, что у нее есть опыт в конкретной технологии, которая документируется. В результате, мы, технические писатели, часто представляем себя аудиторией.
Проблема 3: Код требует понимания конкретного языка программирования
Исходя из упомянутого пункта выше об аудитории получаем следующий факт.
Технические писатели часто не знакомы с языком программирования, или, если технические писатели знакомы с программированием, проект может быть на незнакомом языке. Таким образом, мы сразу же оказываемся в невыгодном положении и вынуждены пользоваться учебными пособиями, чтобы понять основы того, что происходит в коде. Но мы не документируем основы — мы документируем, как реализовать код в определенном контексте, часто на продвинутом уровне. Знание того, как работает код, просто предполагается. Мы должны пройти курс Advanced Calculus и объяснить множители Legrange, зная простую алгебру.
Проблема 4: Отслеживание работы примеров кода от релиза к релизу потребует большой поддержки
Другая задача: понимать, что пример кода работает от релиза к релизу.
Если есть примеры кода, перенесенные в документацию, а не извлеченные из центрального репозитория, может быть сложно даже определить весь код, который нужно протестировать и поддерживать. Проверяется ли это с каждым выпуском? Насколько тестируемым будет код? Часть кода может просто выполняться достаточно легко, но иногда может и потребовать создания примеров приложений или установки других технических сред, для работы. И возможно, придется добавить контекстный код, чтобы код мог реально работать, возможно, даже создавая пример данных или другую информацию, чтобы можно было вернуть правильные значения.
Проблема 5: У инженеров гораздо лучше наметан глаз на хороший и плохой код
Наконец стоит отметить, что, иногда, при документировании кода можно почувствовать себя немного посторонним, как будто пишущим о культуре или стране, к которой не принадлежишь. Технические писатели часто являются посторонними для разработчика. Не будучи разработчиком, можно даже не осознавать, что ваш код плохой.
Помните, что инженеры живут и дышат кодом, и многие считают, что код — это поэзия. Эффективная техника в коде (например, рекурсивные циклы, которые расширяют ресурсы по мере необходимости) может быть прекрасной, вызывая эстетику в уме инженера. Маловероятно, что технический писатель будет подходить к коду с таким же почтением и благоговением. Более приземленный подход к коду может затруднить работу с разработчиками.
Важность документирования кода
Несмотря на трудности документирования кода, эту область документации не следует упускать из виду. Спросите разработчиков, что является наиболее важным элементом документации API, и ответ, который вы обязательно услышите снова и снова, — это примеры кода. Включайте образцы рабочего кода, которые разработчики могут легко скопировать и вставить в свою документацию. Примеры кода, которые продемонстрируют, как включить абстракции в реальную реализацию.
Примеры кода, примеры приложений — независимо от формы, просто нужно больше кода.
Ниже видео инженера Рути Бен Дор на конференции «Write the Docs». На вопрос: «Каковы три наиболее важных элемента создания документации API?», Рут ответил (на 4:15):
Я думаю, если вы собираетесь создавать документацию по API, есть три вещи, которые следует либо включить в нее, либо сделать в процессе ее создания. Я думаю, самое важное, если вы хотите, чтобы люди просто начали его использовать, это примеры кода. Существует множество генераторов документации API, которые будут генерировать примеры кода для вас. Иногда они не очень хороши, поэтому нужно иметь кого-то на самом деле, кто проверил бы эти примеры кода, чтобы убедиться, что они действительно работают правильно. Одно дело получить метод и то, как он вызывается, но для разработчика нужно взять его и понять, как создать рабочий код, достигнув этой конечной точки, это совершенно другое. В отличие от того, могут ли они просто копировать и вставлять в консоль браузера, чтобы доказать, что она работает для себя, это действительно хороший способ снизить барьер для входа. Примеры кода огромны, и примеры кода на разных языках, которые люди могут использовать с вашим API.
Почему инженеры постоянны в своем желании видеть код? Примеры кода показывают, как реализовать абстрактное, повествовательное объяснение фактическим способом. В этом смысле они являются чрезвычайно мощными инструментами, помогающими пользователям понять правильные действия.
Несмотря на важность примеров кода, их нелегко реализовать. По этой причине они часто игнорируются или отсутствуют в документации API. На самом деле, примеры кода могут быть самой сложной частью документации, которую должны документировать технические писатели. В этом разделе разберемся, почему документирование кода может быть сложной задачей, а затем в дополнительных темах рассмотрим конкретные стратегии для успешного включения примеров кода в документацию.
Документирование javadoc
При документировании приложения необходима также поддержка документации программы. Если документация и код разделены, то непроизвольно создаются сложности, связанные с необходимостью внесения изменений в соответствующие разделы сопроводительной документации при изменении программного кода.
Как правило, все существующие среды разработки IDE приложений Java предлагают решение по связыванию кода с документацией в процессе разработки с использованием javadoc. Для этого необходимо соответствующим образом написать комментарий к коду, т.е. документировать. Java комментарии необходимы как для комментирования программы, так и для составления или оформления документации.
Разработан специальный синтаксис для оформления документации в виде комментариев и инструмент для создания из комментариев документации. Этим инструментом является javadoc, который обрабатывая файл с исходным текстом программы, выделяет помеченную документацию из комментариев и связывает с именами соответствующих классов, методов и полей. Таким образом, при минимальных усилиях создания комментариев к коду, можно получить хорошую документацию к программе.
javadoc — это генератор документации в HTML-формате из комментариев исходного кода Java и определяет стандарт для документирования классов Java. Для создания доклетов и тэглетов, которые позволяют программисту анализировать структуру Java-приложения, javadoc также предоставляет API. В каждом случае комментарий должен находиться перед документируемым элементом.
При написании комментариев к кодам Java используют три типа комментариев :
// однострочный комментарий; /* многострочный комментарий */ /** комментирование документации */
С помощью утилиты javadoc, входящей в состав JDK, комментарий документации можно извлекать и помещать в НТМL файл. Утилита javadoc позволяет вставлять HTML тэги и использовать специальные ярлыки (дескрипторы) документирования. НТМL тэги заголовков не используют, чтобы не нарушать стиль файла, сформированного утилитой.
Дескрипторы javadoc, начинающиеся со знака @, называются автономными и должны помещаться с начала строки комментария (лидирующий символ * игнорируется). Дескрипторы, начинающиеся с фигурной скобки, например , называются встроенными и могут применяться внутри описания.
Комментарии документации применяют для документирования классов, интерфейсов, полей (переменных), конструкторов и методов. В каждом случае комментарий должен находиться перед документируемым элементом.
javadoc дескрипторы : @author, @version, @since, @see, @param, @return
| Дескриптор | Применение | Описание |
|---|---|---|
| @author | Класс, интерфейс | Автор |
| @version | Класс, интерфейс | Версия. Не более одного дескриптора на класс |
| @since | Класс, интерфейс, поле, метод | Указывает, с какой версии доступно |
| @see | Класс, интерфейс, поле, метод | Ссылка на другое место в документации |
| @param | Метод | Входной параметр метода |
| @return | Метод | Описание возвращаемого значения |
| @exception имя_класса описание | Метод | Описание исключения, которое может быть послано из метода |
| @throws имя_класса описание | Метод | Описание исключения, которое может быть послано из метода |
| @deprecated | Класс, интерфейс, поле, метод | Описание устаревших блоков кода |
| Класс, интерфейс, поле, метод | Ссылка | |
| Статичное поле | Описание значения переменной |
Форма документирования кода
Документирование класса, метода или переменной начинается с комбинации символов /** , после которого следует тело комментариев; заканчивается комбинацией символов */.
В тело комментариев можно вставлять различные дескрипторы. Каждый дескриптор, начинающийся с символа ‘@’ должен стоять первым в строке. Несколько дескрипторов одного и того же типа необходимо группировать вместе. Встроенные дескрипторы (начинаются с фигурной скобки) можно помещать внутри любого описания.
/** * Класс продукции со свойствами maker и price. * @autor Киса Воробьянинов * @version 2.1 */ class Product < /** Поле производитель */ private String maker; /** Поле цена */ public double price; /** * Конструктор - создание нового объекта * @see Product#Product(String, double) */ Product() < setMaker(""); price=0; >/** * Конструктор - создание нового объекта с определенными значениями * @param maker - производитель * @param price - цена * @see Product#Product() */ Product(String maker,double price) < this.setMaker(maker); this.price=price; >/** * Функция получения значения поля * @return возвращает название производителя */ public String getMaker() < return maker; >/** * Процедура определения производителя * @param maker - производитель */ public void setMaker(String maker) < this.maker = maker; >>
Для документирования кода можно использовать HTML теги. При использовании ссылочных дескрипторов @see и @link нужно сначала указать имя класса и после символа «#» его метод или поле.
Среда разработки IDE, как правило, помогает программисту «подсветкой» встроенной документации. На следующих рисунках приведены скриншоты всплывающих окон IDE Eclipse.
Утилита javadoc в качестве входных данных принимает файл с исходным кодом программы, для которого генерируется НТМL файл. Документация для каждого класса содержится в отдельном НТМL файле. Кроме этого, создается дерево индексов и иерархии. Могут быть сгенерированы и другие НТМL файлы.
Сценарии ant и javadoc
Для создания документации можно использовать ant.
Пример сценария (задания) ant для формирования документации к приложению MyProject :
" />
Подробная информация формирования документации представлена на странице Javadoc/Javadoc2
Зачем и как документировать код на Python: основные шаги и советы разработчика
Чистота и лаконичность — едва ли не главные составляющие философии написания кода. Этот подход может значительно упростить и улучшить работу разработчиков и, как результат, повысить качество конечного продукта. Достичь этого поможет правильное комментирование кода и подготовка документации.
Практичний курс від skvot: Артменеджер.
Управляйте творчим процесом.
В этой статье я объясню, как легко выполнить документирование кода. Материал непременно пригодится тем, кто недавно начал практиковать программирование на Python. Более опытные специалисты упомянут некоторые важные моменты в организации своей работы.
Зачем вам документировать код
Любой проект стартует с получения реквайроментов от продакт-команды. Поначалу они достаточно непонятны. Первая задача — превратить эти продакт-реквайроменты в документацию бизнес-флоу, которая в конечном итоге станет основой реальных задач девелоперов.
Для конкретизации требований нужно пообщаться с продакт-командой, спросить по каждому пункту реквайроментов, уточнить разные детали. Именно так у вас появится основа для написания кода.
Теперь представим, что в проект попал новый человек, которому все выглядит незнакомым и непонятным. Бизнес-логика, технологии, конкретные шаги — все это вызывает у специалиста много вопросов и требует от вас много усилий для объяснения. Но это время на разъяснение можно сэкономить благодаря задокументированному коду. Новый специалист сможет сам почитать код, попытается самостоятельно понять его и перейти к написанию фич.
Динамічний курс від skvot: Візуалізація екстер’єрів у 3DS MAX.
Мистецтво в 3DS MAX.
Когда нужно начинать комментировать код
Самое эффективное и простое документирование кода — во время его имплементации.
Когда у вас сформированы более или менее четкие бизнес-реквайроменты и вы переходите к созданию фактически Proof of Concept, сразу начинайте документировать код.
Ведь вы только что обсуждали с продакт-командой детали проекта и создавали фрагменты будущей реализации. Сложившееся понимание продукта легче добавлять к коду. Так уже на ранних стадиях проекта вы сделаете его понятным всем привлеченным разработчикам.
Отец Python Гвидо ван Россум говорил: «Код гораздо чаще читается, чем пишется». Мы все это прекрасно знаем, но насколько это правда важно! Иногда разработчики забывают об этом, потому что не видят выгоды от этого именно в момент создания продукта. И зря.
Это немного похоже на написание тестов. Они не помогают улучшить продукт прямо сейчас, но в значительной степени влияют на дальнейшие процессы и приобретают все большую ценность с развитием и масштабированием проекта.
Основные шаги в документации кода
- Добавление док-стрингов
Это можно делать в функциях, классах, методах, переменных. Так вы можете объяснить, что выполняют определенные элементы кода. Сделать это можно по-разному. Я, например, после получения документации и комментариев от продакт-команды часто добавляю их фрагменты в модели или в классы — так удобнее.
Професійний курс від robotdreams: Алгоритми та структури даних.
Знаходьте нестандартні рішення у складних робочих задачах.
- Комментарии к любым непонятным частям кода
Иногда определенный фрагмент может отрабатывать только одну маленькую бизнес-логику, незнакомую стороннему разработчику. Комментарии помогут понять, почему все сделано именно так. Эти пояснения следует вписывать сразу после кода.
Помогает сделать код более ясным и лаконичным. При знакомстве с функцией с задекларированными типами становится очевидным, что она представляет собой и какие типы аргументов следует добавлять.
Писать следует не только о том, что делает конкретная функция, но и о том, как она работает в реальном флоу-проекте, какую часть выполняет эта функция в существующем флоу.
Тесты сами по себе могут служить видом документации. Разработчик поймет функционал проекта, просто читая хорошо написанные тесты. Тем более когда каждый тест-кейс задокументирован.
И еще один совет: если вы используете Django-аппликации и Django REST Framework, то обязательно применяйте Swagger .
Подробнее об этом я расскажу чуть позже.
Програмний курс від robotdreams: С++ для GameDev.
Розробка ігор на високому рівні.
Перейдем к примерам
Многие разработчики не знают, где искать методы документирования кода, 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 есть несколько основных функций, построенных вокруг трех целей:
Благодаря drf-spectacular можно получать как можно больше информации из имеющихся функций и классов. Правда, это касается только Django REST Framework.
- Добавление функционала при кастомизации
Имея drf-spectacular, у вас есть дополнительные возможности для более элегантного и расширенного документирования. Очень полезно для кастомизированных элементов, например сериалайзера. Если вы изменяете его, допустим, из-за использования метода to representation, то drf-spectacular может не подхватить эти изменения автоматически. Тогда возникает ошибка об отсутствии полей этого сериалайзера. В таком случае вы должны задекларировать в API view или ViewSet другой сериалайзер, а тот, что с методом to representation, использовать именно в коде:
Благодаря этому у ViewSet не будет сериалайзера с методом to representation. Вы сможете декларировать все филды, которые используете в этом методе для возврата данных:
- Генерация схемы для популярных клиент-генераторов
Пекедж drf-spectacular использует все законы OpenAPI. Это набор правил, описывающих создание любого RESTful-сервиса. Для этого используется Swagger UI.
Что касается технических особенностей drf-spectacular, то он поддерживает многие пекеджи, перечень которых приведен на картинке ниже. Также он требует Python не ранее версии 3.6 и одной из нескольких версий Django и Django REST Framework.
Полезный функционал drf-spectacular
Этот декоратор позволяет многое кастомизировать в эндпоинтах. Представим листинг фильмов, где вы добавляете в методе get queryset определенные фильтры. Если клиент придаст в query-параметрах дополнительные значения, например для выборки снятых после 1986 года фильмов, то drf-spectacular не найдет информацию в коде о возможности такой фильтрации. Но через аргумент вы можете добавить необходимые API параметры из этого эндпоинта. Можно указать название параметра, тип, локации, описания, примеры и формат использования этого параметра. К тому же здесь есть description для документирования методов из ViewSet или View.
По большей части при наличии ViewSet не нужно изменять метод list, как это сделано в предыдущем примере. Вы просто вызываете этот метод сверху строчки. Однако это можно сделать другим способом — с использованием extend_schema_view , которая будет крепиться к ViewSet . Так можно указывать довод, какой метод нужно декорировать. По сути, это тоже самое, но первый пример касался метода, а этот — самого View .
Этот функционал требуется для кастомизации филдов сериалайзера. Сам по себе drf-spectacular не знает, какой тип объекта возвращается и какие манипуляции есть в этом методе. Но мы можем декорировать сериалайзер метод field , скажем, для указания выводимого типа следующим образом:
- @extend_schema_serializer
Позволяет запечатлеть филды и добавить экземплы. В примере я это не использовал, но функционал считается основным для drf-spectacular .
При модификациях аутентификации и авторизации нужно добавлять к проекту 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-код…
К чему я веду: будьте ответственны и при написании кода обязательно подробно документируйте его. Эти усилия в будущем сохранят время и нервы вам и вашим коллегам и улучшат качество конечного продукта.
Если вы нашли ошибку, пожалуйста, выделите фрагмент текста и нажмите Ctrl+Enter.
Строки документации в Python. Документирование модуля, класса, методов
Поскольку в языках программирования, в том числе Python, существует большое количество встроенных и предоставляемых третьими сторонами модулей, то помнить их все, в том числе их функционал, невозможно. Поэтому важно документировать код. Под документированием понимаются не комментарии, а так называемые строки документации, которые принято добавлять в начало модуля, класса, метода или функции.
Основное назначение комментариев – пояснить что делает код, как он работает. Основное назначение строк документации – кратко описать в целом для чего предназначен объект, какие аргументы принимает, и что возвращает.
—>
В исходном коде Python строки документации заключаются в тройные кавычки и пишутся сразу под заголовком объекта. Пример документированного модуля:
"""Модуль содержит классы плоских фигур.""" from math import pi, pow class Rectangle: """Класс Прямоугольник.""" def __init__(self, a, b): """Конструктор принимает длину и ширину.""" self.w = a self.h = b def square(self): """Метод для вычисления площади.""" return round(self.w * self.h, 2) def perimeter(self): """Метод для вычисления периметра""" return 2 * (self.w + self.h) class Circle: """Класс Круг.""" def __init__(self, radius): """Конструктор принимает радиус.""" self.r = radius def square(self): """Метод для вычисления площади круга.""" return round(pi * pow(self.r, 2), 2) def length(self): """Метод для вычисления длины окружности.""" return round(2 * pi * self.r)
Извлекать строки документации можно двумя способами:
- Через встроенный для каждого объекта атрибут-переменную __doc__ .
- С помощью встроенной в Python функции help , которая запускает интерактивную справочную систему.
>>> import planimetry >>> planimetry.Rectangle.__doc__ 'Класс Прямоугольник.' >>> print(planimetry.__doc__) Модуль содержит классы плоских фигур.
Если дать команду help(planimetry) , то будут выведены все строки документации модуля в структурированном виде. Однако можно «заказывать» справку по отдельным объектам:
>>> help(planimetry.Circle.length) Help on function length in module geometry.planimetry: length(self) Метод для вычисления длины окружности.
Выход из справки осуществляется с помощью клавиши q .
В Python документированы все встроенные объекты и модули библиотеки.
>>> print(str.__doc__) str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.
>>> import math >>> print(math.trunc.__doc__) Truncates the Real x to the nearest Integral toward 0. Uses the __trunc__ magic method. >>>
Таким образом, если вам надо узнать, для чего предназначена та или иная функция, и как она работает, это всегда можно сделать, не выходя из интерпретатора Python. Перечень атрибутов модуля или объекта можно посмотреть с помощью встроенной функции dir() .
Следует отметить, документирование модулей принято выполнять на английском языке. Многие проекты имеют открытый код, выкладываются в Веб, их смотрят и дорабатывают программисты из разных стран. Использование одного языка позволяет им понимать друг друга. Поэтому профессиональный программист должен владеть английским хотя бы на начальном уровне. Google Translate – тоже вариант.
Практическая работа
Выполните полное документирование модуля, созданного в практической работе прошлого урока.
Курс с примерами решений практических работ:
pdf-версия
X Скрыть Наверх
Объектно-ориентированное программирование на Python