---
title: Документация проекта и кода
date: 2008-01-21T10:00
tags: [управление]
---

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

<!-- truncate -->

1. Заказ. Клиент заказывает проект, незная примерно чего он хочет.
2. Предложение. Компания хвалится что уже делала много подобных проектов и спрашивает детали и плавно переходит к заключению договора.
3. Разработка
    1. Анализ - много беседы с клиентом что-бы понять его ситуацию и его нужды. Результат анализа - **техническая спецификация**, т.е. **минимальные** требования которым должен соответствовать продукт
    2. Дизайн - проектирование на высоком уровне БД и оценка необходимых задач
    3. Реализация
    4. Конечное тестирование
    5. **Документирование**
4. Поддержка (Support)
5. Оценка квалитета

Цель _спецификации_ — определение [требуемых (must), желательных](http://www.wikiwand.com/en/MoSCoW_method)  (should), и низкоприоритетных (could/would) функциональных требований в минимальных [нефункциональных условиях](http://www.wikiwand.com/en/Non-functional_requirement).

Цель _документации_ в предоставлении детальной информации о конечном продукте/системе. Если в анализе рассматривались абстрактные пользователи, процессы, связи, то в документации всё чётко.

---

### Возможности пользователя  

Ключевые слова для этой документации - use cases и user's manual. В use'case-ах описываются действия пользователя и маршруты как реагирует система. В user's manual описываются те же возможности пользователя, но как правило с более графическими возможностями и с меньшим количеством технических деталей

### Автоматическое документирование кода

Если wiki ещё может быть полезным программистам, то Office Word - наврядли. Всё дело в неудобном оглавлении, необходимости кроссылочности и связями с кодом. Поэтому для документирования кода используют программы-генераторы, сканирующие файлы проекта в поиске комментариев. Если же комментариев нет, а как работает система вы не знаете то прийдётся заняться неприятной работой reverse-engineering'а.

Многие IDE (Zend, Visual Studio, Netbeans) уже включают в себя средства документирования, но никакого общего стандарта до сих пор нет. В своём большинстве, цель генераторов - составить нечто типа энциклопедии всех функций, классов, объектов, иерархий классов, связей между файлами, используемые компоненты и третьи программные продукты. Вся эта огромная информация редко когда может быть полезна начинающему программисту, которому в действительности сначала нужны UML схемы общей архитектуры:

- Логические разделы или то что видет пользователь (use case, интерфейс, цель инфосистемы)
- Общий вид потока информации (связь с БД, темплейты, сервисы, глобальные объекты)
- Соответсвие логическим разделам физическим файлам и таблицам БД (модульность платформы)

Генераторы можно условно разделить на:

- Универсальные  
    - [Doxygen](http://www.stack.nl/~dimitri/doxygen/) для C, Java, Python, PHP. На выходе - html, pdf, man, pdf, rtf.
    - [NaturalDocs](http://naturaldocs.org/)
    - [AsciDoc](http://www.methods.co.nz/asciidoc/)
    - [doc-o-matic для](http://www.doc-o-matic.com/) Matlab, ASPX, JSP, IDL, Delphi, C#, VB, Java, PHP
- Специфичные  
    - [javadoc](http://java.sun.com/j2se/javadoc/) для Java
    - [phpDocumentor](http://www.phpdoc.org/) для PHP
    - [docutils](http://docutils.sourceforge.net/)
    - [NDoc](http://ndoc.sourceforge.net/), [Sandcastle](http://www.codeplex.com/SHFB), [GhostDoc](http://www.roland-weigelt.de/ghostdoc/) для .NET
    - [pasdoc](http://freepascal.ru/article/raznoe/20060301170731/) для Delphi
    - [ZenDoc](http://zendoc.org/) для ActionScript

Генераторы как правило по-своему хранят данные и комментарии, завися от языка, однако последние тенденции например в Visual Studio показывают популяризацию xml. [DocBook](http://www.docbook.org/) - одна их предлагаемых универсальных схем.

### Внутренняя документация (Developer's guide)

Обычно делается в wiki/confluence и включает в себя

- Концептуальный обзор — какие сущности и какие связи используются (Concept diagram, DB schema)
- Согласованный **стандарт кода** для проекта, т.е. какой синтаксис используется для разных типов кода (PHP, Javascript, SQL, RegExp..)
- Архитектурный обзор — какое ПО используется на сервере, как управляются серверы, как обновляются, какие среды для разработки существуют
- Как развернуть приложение у себя (installation guide)
- Какой workflow для разработки одной задачи — что надо менять/отмечать в issue tracker'е, как писать миграции
- Диаграмма классов (Class diagram) — на случай если часть кода (библиотека) достаточно сложная, то имеет смысл методы и свойства нарисовать в контексте этого набора

### Документирование внешних API

Cвязано с автоматическим документированием кода - передаваемые параметры хочется напрямую получать из кода и соответсвующих контроллеров, что-бы не происходило рассинхронизации кода от документации. Но нужен и guide для разработчиков с библиотеками и/или примерами использования этого API

### Roadmap

Я предпочитаю выделять и группировать задачи в виде mind map - это позволяет визуально выделить (размером шрифта), большие и кластерные задачи.

Читайте также:

- [Техническое задание](http://www.dserg.com/documentation) (ТЗ)
- [Процесс документирования](http://stump-workshop.blogspot.com/2007/08/blog-post_09.html)
- Почему при [гибких методах разработки](http://wiki.agiledev.ru/doku.php?id=tdd:tdd_and_documentation) (agile development) документация ведётся редко

## Related

- [Estonian Mafia](/ru/blog/философия/estonian-mafia/)
- [OpenUP](/ru/blog/философия/openup/)
- [Rapid application development](/ru/blog/философия/rapid-application-development/)