ПР №10 СиПИ. Практическая работа 10 Документирование разработки по Цель работы
 Скачать 286.27 Kb.
|
|
Практическая работа №10 – «Документирование разработки ПО» Цель работы Получить навыки по формированию документации разработчика, формирование документации пользователя. Документация разработчика Сопровождение недокументированного кода является достаточно сложной задачей, затрачивающей большое количество сил разработчика. Документированный программный продукт облегчает задачу доработки программного обеспечения, поскольку сразу становится ясно, какой участок кода за что отвечает без необходимости изучения каждой его строчки. Несколько основных причин для разработки документации для кода: Обслуживать код становится достаточно проблематично, если к нему не применялся должный уровень документирования. Особенно это актуально для поддержки использования кодов другими программистами, что работают над проектом. Если потребуется задействовать других программистов посредством технологии открытого кода. При начале масштабной коллективной работы документирование кода становится безотлагательным делом. При наличии документирования кода логика заметно проясняется, а код улучшается по своей структуре. Код, не прошедший документирование, неудобен в работе не только при передаче на сопровождение, но также непрост в самостоятельном сопровождении. Написание документации к программному обеспечению является достаточно трудоемким процессом, для облегчения которого разрабатываются различные программные средства, позволяющие собрать документацию разработчика из комментариев исходного кода, примером такого ПО может послужить Doxygen. Doxygen Вероятнее всего, многие сталкивались с результатами работы различных генераторов документации. Общий принцип их работы следующий: на вход такого генератора поступает специальным образом комментированный исходный код, а иногда и другие компоненты программы, а на выходе создаётся готовая документация для распространения и использования. Рассматриваемая система Doxygen как раз и выполняет эту задачу: она позволяет генерировать на основе исходного кода, содержащего комментарии специального вида, читабельного вида документацию, содержащую в себе ссылки, диаграммы классов, вызовов и т.п. в различных форматах: HTML, LaTeX, CHM, RTF, PostScript, PDF, man-страницы. Данная система поддерживает много различных языков, например: C++, C, Objective-C, C#, PHP, Java, Python, IDL, Fortran, VHDL, Tcl, и частично D. Doxygen позволяет создавать документацию типа HTML и представляет собой консольную программу наподобие классики в стиле Unix. Принцип работы напоминает компилятор, который анализирует исходные тексты с созданием документации. Основное преимущество в процессе использования Doxygen подразумевает определённую последовательность документирования исходного кода. Оказывается эффективная помощь при создании структуры кода с применением недокументированного исходного файла. Главное, осуществить надлежащие настройки. Sphinx Выступает в роли популярного инструмента для создания документации в текстовом виде и преобразования в различные форматы. Очень удобен при использовании версиями в системах управления, отслеживающими возможные изменения. Доступ возможно получить согласно лицензии BSD. Совместимыми языками программирования являются Python, C, C++. Наравне документацией проектного типа может документироваться код и происходит избавление от рутины, а типовые проблемы разрешаются автоматически. К ним относятся индексирование заголовков и особое выделение кода, к примеру, при присутствии фрагмента кода в документе. При этом определённым образом выделяется синтаксис. Если система разрабатывается на языке, не входящем в список doxygen или sphinx, можно воспользоваться другими генераторами документации, к примеру, Jazzy для языка Swift. В итоге, в данном разделе должны быть приведены примеры написанной документации разработчика, показывающие её реализацию. Помимо этого, к работе должен быть приложен архив со сгенерированной документацией. Документация пользователя Документация разработчика позволяет подробно изучить то, как устроено приложение с точки зрения программиста, однако у пользователя также могут возникать вопросы в процессе эксплуатации ПО. Для ответов на эти вопросы должна быть разработана документация пользователя, содержащая инструкции по различным функциям приложения. Достаточно удобным форматом документации является написание Wiki по проекту, которое освещает каждую функцию приложения в отдельности. FANDOM Фэ́ндом (англ. Fandom, Fandom powered by Wikia), ранее известный как Ви́кия (англ. Wikia) — бесплатный сервис хостинга, предоставляющий возможность любому желающему создать свой собственный тематический вики-проект или принять участие в коллективной работе над уже существующими проектами. Уровень разработки содержания в проектах Фэндома разный. На сайте каждый зарегистрированный участник может создать новую вики. Но поскольку желание или возможность их развивать с нуля есть не у всех, большинство из них забрасываются. Проекты-пустышки сразу не удаляются (если длительное время в вики не наблюдается активности, то замораживается база данных, а если никто не заинтересуется дальнейшей судьбой вики, вики удаляется с сохранением истории правок в архиве, если такие были), поэтому на один действующий и обновляющийся проект приходятся несколько десятков заброшенных. Также множество вики были созданы самими участниками для различных тестов, что уже гарантирует тот факт, что развиваться они не будут. Ранее на сайте было множество проектов-дубликатов, созданных по обыкновению участниками, которые не смогли наладить диалог с администрацией основного проекта. Это создавало путаницу для новопришедших людей. В 2020 году инструмент создания вики был переработан: теперь он автоматически блокирует создание дубликата, если находит вики на данную тематику. MediawikiMediaWiki — это распространенная wiki-система. Документы в wiki хранятся в виде плоского текста с использованием некоторого языка разметки. Текст можно править «по месту» в процессе чтения материала и немедленно публиковать. Следующий момент — облегченная схема построения гиперссылок. В wiki-системе соблюдается цепочка Идентификаторы=Названия=Заголовки и используется адаптивная линковка, заключающаяся в перенаправлениях и даже «опережающих» ссылках на несуществующие еще статьи. Наконец, wiki-система обеспечивает централизованное хранение, что для большинства пользователей удобнее работы со множеством файлов размеченной (HTML, XML, LaTeX, SGML) документации. Не требуется одновременно знать и файловую структуру проекта, и идентификаторы разделов (для ссылок) и иметь систему синхронизации изменений от различных пользователей. Совместное редактирование влечет совместную ответственность за результат, вырабатывается культура обсуждений и поиска правильного решения, легкость редактирования ведет к многократным итерациям, что улучшает качество текста. Кроме того, легкость порождения статей способствует фиксации больших объемов знаний. В wiki-системе на основе MediaWiki не дублируются знания, доступные в Сети, а содержит исключительно внутреннюю уникальную информацию: описания внутренних технологий, регламентов, инструкций, FAQ-списки, библиотеку, личные странички сотрудников с квалификационными профилями и т.п. Задание Создать документацию разработчика при помощи любого инструмента для генерации документации кода; Создать документацию пользователя при помощи FANDOM или MediaWiki (можно предложить что-то свое). Дополнительные ссылки для ознакомления: Документация при помощи Sphinx [Электронный ресурс] / https://www.sphinx-doc.org/en/master/ Doxygen для скачивания на Windows, Linux, MacOS [Электронный ресурс] / https://disk.yandex.ru/d/oRbYFrowgm05hQ Mediawiki [Электронный ресурс] / http://www.mediawiki.org/wiki/MediaWiki FANDOM [Электронный ресурс] / https://www.fandom.com/ Проект Demon's work студентов ИКБО-07-18 / https://demons-work.fandom.com/ru/wiki/Demon's_work_%D0%92%D0%B8%D0%BA%D0%B8#gallery-0 |