Цель данного документа - показать начинающему "культурному" программисту одно из некоммерческих решений проблемы автоматического документирования, которое дает по-моему отличные результаты. 

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

Большие дяди перед написанием кода пишут документ, определяющий что этот код будет делать.
Но, когда дело доходит до реализации (имплементации), всё пишется с теми же интерфейсами, но чуточку по-другому, чем планировалось. Поэтому документация кода внутри исходников - незаменима (если у вас конечно получается писать настолько чисто и классически, что сам код настолько прост и самоописаем, что документация вам не нужна.
Обычно же хочется быть способным погулять по коду, а точнее по его документации, посмотреть глазами на связи меж структурами данных, и без особого напрягу всё это запомнить. Также хочется, чтобы из данной документации были ссылки на живой код, и можно было посмотреть полные списки классов, структур, файлов проекта и т.д.
Фактически нужен инструмент автоматического создания документации, который бы прошелся по коду, и извлек из него заметки, описания, определения, всё, и уложил бы эту информацию в HTML, чтобы было легко почитать это через пару лет, и понять: что же мы тут наделали?
Kроме написания своими руками парсера документаци, одно из самых доступных, причем бесплатно, решений этой проблемы - Доксиджен.


Примечание:
В данной статье опускаются опасности разных методов документирования и написания кода. Насчет опасностей - писать дурацкий код, с дурацкими комментариями - это независимая опасность от doxygen.
Если человек писАть не умеет, то ему учиться надо. Я исхожу из того, что документуруется то, что нужно и как нужно. И задача, решение которой тут описано - создание на основе кода + комментариев документа (напр. PDF, LaTeX, RTF, или HTML каталог) со следующими "параметрами":

• удобного для чтения, со ссылками в код
• индекс элементов кода с пояснениями
• иллюстрации связей между различными компонентами программы

т.е. дебаты о целесообразности одного или другого стиля комментирования тут не актуальны.



Идея - не писать вручную дополнительные "служебные" ключевые слова на каждой строке кода для комментирования, а просто комментировать, почти "незаметно" для себя.

Установка
Домашняя страница проекта - тут
Скачать и установить можно оттуда. Процесс установки довольно простой:

• На системах GNU/линукс или UNIX проще всего довериться дистрибутиву. Пакет поставляется в дистрибутиве.
• На системах Микрософта doxygen придется предварительно скачать и установить:
  • реализацию LaTeX для Winows, напр. MikTeX
  • реализацию ghoststrip, напр. эту
  • для создания  помощи в формате HTML в стиле Windows нужно скачать пакет Microsoft HTML help workshop
  • Далее качается и ставится сам пакет Doxygen.

Принцип работы с инструментом прост: 
Комментирование исходников делается по простому принципу, описанному ниже. Далее создается кофигурационный файл настроек работы Doxygen, и в заключение она запускается. После этого создается каталог, с существующим индексом index.html, с которого можно начать просматривать готовую документацию. Вид документации можно контролировать при помощи специального CSS файла (не обязательно), чтобы придать ему "свой" стиль.

Этапы работы с doxygen:

• "Незатруднительное" комментирование кода
• создание конфигурационного файла
• запуск генератора документации doxygen

О каждом этапе в расширенной форме - ниже.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
"Незатруднительное" комментирование кода
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
создание конфигурационного файла
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
запуск doxygen
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Ту Би Континьюд

еще не помешает установить graphviz, пакет визуализации графов
с его помощью doxygen может рисовать UML схемы

вообще в коде выглядит это так:

doxygen поддерживает разные яп и разные форматы документирования, не только тот что я привел 

Когда я читаю исходники докуметнированные doxygen - я сильно матерюсь, так комментариев настолько много, что желание читать исходники пропадает сразу же, особенно в хедерах, где описан интерфейс класса.  Когда комментарий в 1 строку - это нормально, когда 20 - для хедера нет, для соурса тоже нормально, если обьясняется что-то нестандартное. Тем более как правило нормальные программисты называют идентификаторы и функции так, что они сами документируются и когда ты читаешь их сразу все понимаешь. Естественно если программист пишет string a, int b - таких нужно сразу увольнять, пускай опен соурс пишут.
Этому еще на первых курсах учат - не пишите комментарий там где он будет лишним.



Это сообщение отредактировал(а) Torsten - 10.7.2008, 09:48

ну во первых, можно свернуть комментарии в IDE(если конечно IDE поддерживает folding)...
ИМХО doxygen все-же удобнее вики, не всегда смысл кода очевиден, иногда бывают всякие неявные соглашения, например, что какая-то функция не может быть вызвана из любого потока а только из GUI потока, или еще что нибудь в этом роде, так что документацию нужно писать. Это особенно хорошо начинает чувствоваться с большим проектом, когда работаешь над одной частью проекта достаточно долго, забываешь что и как в другой части проекта и приходится читать документацию или анализировать код если ее нет  

Lazin, одно из свойств doxygen, которое действительно раздражает, при чтении комментов "приготовленных" под doxygen, это обозначения в таком вот стиле (кстати у тебя там опечатка: \brief, а не \breif)

я скоро добавлю, то что рекомендую:


т.е. принцип - как можно меньше "внешних" коду ключевых слов.
Насчет опасностей - писать дурацкий код, с дурацкими комментариями - это независимая опасность от doxygen.
Если человек писАть не умеет, то ему учиться надо.

Добавлено @ 11:08

И это начинает быть обязательным, когда проект разрабатывает не один человек, и в процессе могут уйти одни люди, и прийти другие.

Lazin, 

Я работаю над большими проектами (а точнее над некоторыми из их частей), люди бывают и уходят и приходят - doxygen не используем и потребности в нем нету. В основном весь рабочий код находятся в внутрифирменных библиотеках, в продакш приложениях реализуется логика, посредством определенных правил.

Torsten, ты хочешь сказать, что у вас код вообще не документирован?
если что, тема обсуждения - doxygen, а не необходимость документации к коду

Это сообщение отредактировал(а) Lazin - 12.7.2008, 23:40

Lazin, 
Код пишется так, что он автоматически документируется. Я уже об писал, если функции и переменные называются int foo(string a) - таких нужно сразу увольнять. Примеры как раз таки приведены в этой теме. Вообщем эти моменты в книгах обсуждают. Самая наверное лучшая - Совершенный код, от Макконела.
 
Естественно главное детали проектов (диаграммы классов, компонентов) и guides с examples по использованию находятся на вики.

Это сообщение отредактировал(а) Torsten - 13.7.2008, 11:10

В одной из тем ты утверждал, что вы не используете диаграммы, ибо нет надобности и времени: 



А теперь диаграммы классов одна из основных деталей ваших проектов. Быстро пересмотрели свои взгляды