Instrumentalnye-sredstva-oformleniya-i-dokumentirovaniya-algoritmov-programm (1).pptx

Instrumentalnye-sredstva-oformleniya-i-dokumentirovaniya-algoritmov-programm (1).pptx

1. Инструментальные средства оформления и документирования алгоритмов программ Часть 2: Продвинутые подходы Погружение в продвинутые методы автоматической генерации документации, UML-моделирование и интеграцию документирования в современный цикл разработки.

2. Что мы усвоили из Части 1? 01 Важность документирования Необходимость для понимания, поддержки, обучения и обеспечения качества 02 Что документировать От требований и архитектуры до кода и пользовательских руководств 03 Комментарии в коде Объяснение 'почему' и сложных участков программы 04 Соглашения по кодированию Единообразие и читаемость кода 05 Псевдокод и блок-схемы Универсальные инструменты описания алгоритмов

3. Автоматическая документация из исходников Концепция Специальные комментарии в коде обрабатываются инструментами для генерации документации в HTML, PDF, RTF Преимущества Актуальность документации Снижение дублирования Удобство и согласованность Javadoc Стандарт для Java API-документации с тегами @param, @return, @throws Doxygen Универсальный инструмент для C++, C, Java, Python, PHP, C# Sphinx Создание красивой документации для Python-проектов

4. Как это выглядит на практике Исходный код Специальные комментарии /** */ с тегами @param, @return, @throws Обработка Javadoc/Doxygen анализирует комментарии и структуру кода Результат HTML-страницы с отформатированной документацией методов /** Calculates the factorial of a non-negative integer. * @param n The non-negative integer * @return The factorial of n * @throws IllegalArgumentException If n is negative */ public long calculateFactorial (int n) { if (n < 0) throw new IllegalArgumentException (); long result = 1; for (int i = 1; i <= n; i ++) result *= i ; return result; }

5. Как это выглядит на практике <h3>Method: calculateFactorial (int n)</h3> <p>Calculates the factorial of a non-negative integer.</p> <p>This method computes the factorial using an iterative approach.</p> <h4>Parameters:</h4> <ul> <li><code>n</code> - The non-negative integer for which to calculate the factorial.</li> </ul> <h4>Returns:</h4> <ul> <li>The factorial of n.</li> </ul> <h4>Throws:</h4> <ul> <li><code> IllegalArgumentException </code> - If n is negative.</li> </ul>

6. README: Точка входа в проект README-файл — это 'визитная карточка' проекта в корневом каталоге, критически важная для открытых и внутренних проектов. 1 Название и описание Что это за проект и какую проблему он решает 2 Установка Подробные инструкции по установке зависимостей и настройке окружения 3 Использование Примеры использования основных функций или запуска приложения 4 API и вклад Описание методов и правила для пулл-реквестов 5 Лицензия и контакты Тип лицензии, информация о поддержке, статус CI/CD

7. Динамическая база знаний Wiki-системы для командной документации Веб-платформы для создания, редактирования и связывания страниц с простым синтаксисом разметки. Совместная работа и коллективное владение знаниями Простота использования и интуитивный интерфейс Гибкость, динамичность, централизованное хранение История изменений и мощный поиск Confluence Корпоративное решение от Atlassian с интеграцией Jira и Bitbucket GitHub/GitLab Wiki Интегрированные Wiki для небольших и средних проектов MediaWiki Движок Wikipedia, мощный, но требует настройки

8. Документация под контролем версий Хранение документации рядом с кодом в Git — одна из лучших практик современной разработки. История изменений Отслеживание, кто, когда и какие изменения внес в документ Совместная работа Одновременная работа над разными частями с последующим merge Версионность Документация привязана к конкретной версии кода Актуальность Изменения кода и документации в одном коммите Автоматизация Интеграция с CI/CD для генерации и публикации Примеры документов в VCS: README-файлы, маркдаун-файлы, схемы Draw.io/PlantUML, конфигурационные файлы

9. Унифицированный язык моделирования (UML) Стандартизированный графический язык для визуализации, спецификации и документирования компонентов программных систем. Диаграммы классов Статическая структура: классы, атрибуты, методы, отношения Варианты использования Функциональность с точки зрения пользователей Диаграммы последовательности Динамическое взаимодействие объектов во времени Диаграммы активности Поток управления и параллельные процессы Диаграммы состояний Поведение объекта в зависимости от состояния

10. Программы для UML Enterprise Architect Мощный платный инструмент для полного цикла моделирования, генерации кода и реверс-инжиниринга Visual Paradigm Комплексное решение для UML, BPMN, ERD с инструментами совместной работы PlantUML Open source, 'код как диаграмма', хранение в VCS, интеграция с CI/CD Draw.io / diagrams.net Веб-инструмент с базовой поддержкой UML-диаграмм Lucidchart Облачное решение для совместной работы над диаграммами

11. Документация как часть DevOps Интеграция документирования в CI/CD — показатель зрелости процесса разработки. 1 Изменение кода Коммит в репозиторий запускает автоматические процессы 2 Генерация Doxygen, Javadoc, Sphinx создают свежую документацию 3 Проверка Валидация комментариев, проверка ссылок 4 Публикация Автоматическое развертывание на сервере или Wiki Гарантия актуальности Документация всегда соответствует текущей версии кода Экономия времени Автоматизация рутинных задач Снижение ошибок Устранение человеческого фактора Постоянная доступность Последняя версия всегда доступна команде

12. Лучшие практики документирования Советы по созданию качественной документации 1 Начинайте документировать рано и делайте это постоянно Не откладывайте на конец проекта Начните с требований и архитектуры Документация должна развиваться вместе с кодом 2 Определите целевую аудиторию Для разработчиков, пользователей или менеджеров? Язык и детализация должны соответствовать потребностям 3 Используйте правильные инструменты для каждой задачи Javadoc/Doxygen для комментариев в коде README для обзора проекта Wiki для командной базы знаний UML-диаграммы для сложного дизайна 4 Стремитесь к ясности, краткости и точности Избегайте двусмысленностей и лишних слов Устаревшая документация хуже её отсутствия 5 Поддерживайте актуальность Включите обновление в рабочий процесс Сделайте частью проверки кода 6 Храните документацию рядом с кодом (в VCS) Облегчает версионирование и совместную работу 7 Применяйте шаблоны Обеспечивает единообразие Упрощает создание новой документации 8 Получайте обратную связь Просите коллег и пользователей просматривать документацию

13. Документирование как искусство и наука Завершение двухчастной презентации. Осознание глубины и важности темы документирования. 1 Качественно оформленный код Фундаментальное требование для надежных, масштабируемых и поддерживаемых продуктов. 2 Рассмотренные инструменты Комментарии и соглашения по кодированию Псевдокод и блок-схемы для визуализации Автоматическая генерация документации README-файлы и Wiki-системы Управление через системы контроля версий UML для моделирования сложных систем 3 Философия документирования Искусство эффективной коммуникации Наука управления знаниями Инвестиция, окупающаяся на протяжении жизненного цикла ПО Навыки качественного документирования отличают хорошего разработчика от отличного. Код – это лишь часть решения; хорошо документированный код – это полное решение.