exam06 5 - stankin/design-part-2 GitHub Wiki

Документирование программного кода.

Реферат к лекции 6(22): Проектирование конфигурационного управления

Выполнил: Афанасьев Вадим

Проверил: Малаховецкий Дмитрий

Группа: ИДБ-19-07

ГЛАВА 1. ПОНЯТИЕ И ОСОБЕННОСТИ ДОКУМЕНТИРОВАНИЯ ПО

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

трудности с поддержкой чужого кода;
трудности с поддержкой легаси-кода;
трудности с поддержкой личного кода, с момента написания которого прошло определенное время.

Рассмотрим несколько утверждений, в которых подвергается сомнению необходимость в документировании программного кода:

"Этот код прост и понятен"

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

"Этот код устарел"

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

"Документация в коде захламляет код"

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

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

По ГОСТ Р ИСО/МЭК 15910-2002:

документация (documentation): Печатные руководства пользователя, диалоговая (оперативная) документация и справочный текст ("хелпы"), описывающие как пользоваться программным продуктом.

Рассмотрим классификацию документов на программную систему:

Документы, описывающие процессы разработки - часть системной документации;
Документы, описывающие продукты процессов разработки. Эти документы могут быть как системными (например, UML-схемы модулей системы), так и пользовательскими (например, руководства по использованию - README).

Далее приведем несколько "лучших практик" - советов по разработке документации:

Следует комментировать любые фрагменты кода, которые имеют не совсем обычную, нетривиальную логику. Не всегда решения оказываются лаконичными или нетрудными для понимания. Все мыслят по разному, поэтому дополнительные объяснения сослужат хорошую службу остальным сотрудникам, особенно при отсутствии возможности очного взаимодействия;
Рекомендуется оставлять ссылки на примеры использования вашего кода. В случае, если использован общепринятый или разработанный внутри студии паттерн, то можно указать на место, где он подробно расписан. После создания какого-либо плагина наличие использующего его шаблонного проекта значительно упростит жизнь коллегам;
Нужно оставлять пояснения, по каким именно причинам задача была решена тем или иным образом. Может оказаться так, что у других разработчиков появится мысль о более эффективной реализации рассматриваемой логики;
Необходимо соблюдать баланс, золотую середину между чрезмерно подробной документацией и ее абсолютным отсутствием. Здесь же следует упомянуть самодокументирующийся код. Простые классы, функции и конструкции при наличии адекватного нейминга и форматирования объясняют сами себя, в то время как даже хорошо структурированная и спроектированная программная реализация какой-либо сложной логики нуждается хотя бы в минимальных объяснениях примерного хода выполнения. Не стоит заставлять других разработчиков тратить большое количество времени на отладку уже написанного кода в целях в нем разобраться.

Иллюстрации некоторых случаев, связанных с документацией:

Очевидные комментарии:

Сложности при понимании автором своего же кода:

Написание документации позволяет сократить время, затрачиваемое одними разработчиками на объяснение кода другим разработчикам:

Проблемы при отсутствии документации на код, с момента которого прошло немалое количество времени:

Хороший нейминг и соблюдение стиля важны, но не стоит совсем забывать про документирование:

ГЛАВА 2. ИНСТРУМЕНТЫ ДЛЯ ДОКУМЕНТИРОВАНИЯ ПО

В данной главе будут рассмотрены особенности различных инструментов для документирования ПО. Не секрет, что многим программистам элементарно лень тратить время на написание документации, ведь гораздо важнее уделить внимание другим нерешенным задачам. По этой причине были разработаны средства автоматизации данного процесса, что не только позволяет ускорить создание справочной информации, но и снизить количество ошибок, обеспечить единство стиля и прочее. Заметим, что наиболее подробно будут обозрены свойства таких инструментов, как Doxygen и Confluence, так как есть возможность опереться на личный опыт их использования в "боевом" коде.

Doxygen

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

HTML;
LaTeX;
CHM;
RTF;
PostScript;
PDF;
man-страницы.

Широко распространен, в том числе и в нашей студии. Интегрированная среда разработки Microsoft Visual Studio имеет удобный интерфейс установки плагинов, в список которых входит и Doxygen. Обратим внимание на то, что комментарии в исходниках, сгенерированные с помощью Doxygen, обеспечивают удобный интерфейс просмотра справочной информации при наведении курсора мыши на какую-либо функцию либо класс.

После инсталляции перейдем к рассмотрению основного функционала Doxygen.

Документация кода с помощью данного инструмента осуществляется посредством документирующих блоков. Традиционно выделяют следующие подходы к их размещению:

вариант с размещением блоков перед или после объявления или определения класса, поля или метода класса, функции, пространства имен и пр.;
вариант с произвольным размещением, который требует явного указания принадлежности к элементу. Заметим, что данного подхода разработчики рекомендуют избегать.

По своей структуре любой Doxygen-блок можно рассматривать как комментарий, обладающим специальным оформлением. Следовательно, вид блоков зависит от текущего языка программирования.

Различают два основных типа документирующих блоков:

однострочный (краткое описание элемента);
многострочный (подробное описание элемента).

Для наглядности приведем примеры создания Doxygen-комментариев на примере языка C++.

Заголовочный файл:

Определение класса:

Определение функции:

Рекомендации:

Однострочные комментарии с назначением функции в хедере допустимы для функций которые ничего не принимают и ничего не возвращают (например Init());
Однострочные комментарии для переменных не должны требоваться. Название переменной должно отражать ее назначение четко;
В файлах реализации допускается любое количество однострочных и многострочных комментариев;
В однострочных комментариях так же допустимы команды \brief и \details.

Список самых полезных команд Doxygen:

\date Предназначена для указания даты разработки;
\bug Перечисление известных ошибок;
\warning Предупреждение для использования;
\copyright Используемая лицензия;
\example Команда, добавляемая в комментарий для указания ссылки на исходник с примером (добавляется после команды);
\todo Команда, используется для описания тех изменений, которые необходимо будет сделать (TODO).

Confluence

Confluence – это система, созданная компанией Atlassian, предназначенная для накопления, хранения и выдачи структурированной информации в целях обеспечения эффективной командной работы.

Основные термины:

Страница – контент размещается на страницах – динамических документах, которые вы создаете на сайте Confluence. Страницы могут содержать любую информацию: от планов проектов до протоколов собраний, от руководств по поиску и устранению неисправностей до политик и многого другого. Вместе с Confluence поставляются шаблоны, которые помогают создавать прекрасные страницы для любого контента. Если не удастся найти шаблон для нужного типа контента, всегда можно начать с чистого листа.
Раздел – страницы хранятся в разделах – рабочих пространствах, предназначенных для совместной работы и упорядочения контента. Связанный контент лучше размещать в одном разделе, но вы можете создать столько разделов, сколько требуется команде. Например, одна маркетинговая команда может хранить всю работу в одном разделе, выделив на каждую маркетинговую кампанию по одной странице, тогда как другая может создать для каждой кампании отдельный раздел. Одновременно с разделом создается обзорная часть (главная страница) и блог. Это облегчает распространение обновлений и объявлений среди участников команды.
Дерево страниц – систематизировать содержимое раздела помогает иерархическое дерево страниц. Благодаря этому найти нужную информацию можно быстрее и проще. Страницы можно упорядочивать любым способом, создавая вложенные страницы внутри связанных с ними разделов и страниц.

Удобной практикой является создание отдельных статей под каждый блок функционала, в которой, в свою очередь, представлена структурированная и разделенная на заголовки информация. Ссылку на саму статью можно оставить в комментариях в тексте исходного кода, либо в описании задачи в таск-трекере (Jira, Trello и пр.)

Sphinx

Sphinx – это популярный инструмент для документирования ПО, позволяющий создавать текстовые документы и преобразовывать их в различные форматы. Это удобно при использовании систем управления версиями, предназначенных для отслеживания изменений. Он доступен по лицензии BSD и поддерживает несколько языков программирования, таких как Python, C и C++. Он может быть использован как для проектной документации так и для документации кода. Sphinx избавляет от рутинных действий и предлагает автоматическую функциональность для решения типовых проблем, например, индексирования заголовков и специального выделения кода (например, при включении в документ фрагментов кода) с соответствующим выделением синтаксиса.

Pandoc

Pandoc не похож на другие инструменты для документации. Он действует как швейцарский нож и позволяет разработчику быстро конвертировать разметку из одного формата в другой. Pandoc имеет широкий спектр поддержки документов, в том числе textile, reStructuredText, LaTeX, EPUB и т.д. Кроме того, он предлагает несколько расширений синтаксиса разметки, в том числе списки определений, таблицы, сноски и т.д.

Dr.Explain

Front-end разработка также, в определенной степени, требует документирования. Создавать документацию как для обычных, так и онлайн-приложений, написанных на любом языке программирования, в любой среде разработки, с применением любого фреймворка поможет Dr.Explain. Он фильтрует ключевые элементы интерфейса, а затем извлекает связанные с ним метаданные. После этого, разработчик может изменить полученную информацию, чтобы быстро создать документацию интерфейса.

ЗАКЛЮЧЕНИЕ

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

Несомненно, документирование ПО играет большую роль в управлении конфигурацией, но лишь одного данного развитого элемента недостаточно для эффективного функционирования проекта. Не стоит забывать о таких компонентах, как системы контроля версий (Plastic, Perforce, Git), средства контейнеризации (Docker, Kubernetes), непрерывной интеграции и доставки (TeamCity, Jenkins), сетевая топология (Cisco, MikroTik) и прочее.

Документирование применимо ко всем вышеперечисленным элементам и всегда будет оставаться актуальным.