Re: Идеальная система документирования кода
От: x-code  
Дата: 28.12.09 21:01
Оценка: 24 (1) +1
Здравствуйте, AndrewVK, Вы писали:

AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.


У меня уже давно есть идея, правда так до сих пор и не реализованная Даже где-то на форуме высказывал какие-то отдельные мысли...
Документация должна быть интерактивной. Это значит, что всякие доксигены генерируют статическую документацию на основе комментариев, а нужна система, которая ничего бы не генерировала, а позволяла бы работать с документацией прямо из IDE. Т.е. можно было бы вывести документацию, просто ткнув мышью в непонятное место в программе; перемещаться по гиперссылкам; искать разными способами — по контексту, по тегам, по автору, дате и т.д.; максимально быстро, в один щелчек мыши, переходить от кода к связанной с ним документации, и обратно; редактировать документацию прямо из IDE в удобном визуальном редакторе. Система управления документацией должна проверять целостность документации, автоматически находить незадокументированные части кода; части, для которых дата обновления документации меньше даты обновления кода; и т.д.
Документация должна быть интегрирована в систему контроля версий, в багтрекер и систему планирования (т.е., по сути, это уже не классическая "документация", а некая база знаний, "навешенная" на solution с кодом и максимально тесно интегрированная с ним);

Вариантов реализцаии может быть много, но в целом за основу должна быть взята идея "древовидного редактора" (аутлайнера)
Где-то сбоку появляется панель, аналогичная Solution Explorer, в которой в виде иерархического дерева представлена вся документация системы. Ведь документация бывает не только к классам и методам, но и "оторванная" от кода — объясняющая предметную область, особенности сборки проектов и т.д. Поэтому разные узлы дерева должны иметь разные способы связи с кодом. Хорошее решение — иметь один файл документации на один файл исходника, имя файла такое же, а расширение другое.

Также должна быть как минимум еще одна панель — визуальный вьюер/редактор документации (на примере Visual Studio — удобно было бы иметь ее внизу, там где Output, Error List и т.д.). Также, должна быть возможность открытия файлов документации не в панели, а в обычных окнах редактора (на случай если документация большая).

Кроме текстовых (точнее, html) файлов, удобно было бы иметь файлы других типов, в особенности — "диаграммы в свободном стиле" (смесь UML, MindMaps, блок-схем и т.д.).

Документация должна храниться в простых html и xml файлах (а не в единой базе, как это делается во всех аутлайнерах), чтобы разные программисты могли редактировать ее одновременно, и затем независимо друг от друга вносить в систему контроля версий.
 
Подождите ...
Wait...
Пока на собственное сообщение не было ответов, его можно удалить.