Блог

Я рассматриваю возможность потребовать от моей команды более тщательного документирования своего кода для некоторых крупных предстоящих проектов и, чтобы сделать жизнь немного менее болезненной, я ориентируюсь на генераторы XML-документации, такие как Sandcastle, Doxygen или Box Live Documenter.

Какие ключевые соображения я должен учитывать при оценке наилучшего варианта и какой опыт привел вас к конкретному решению?

Для меня ключевыми соображениями были бы:

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

2. Полностью оформленный: Может ли документация быть полностью оформлена так, чтобы она отлично смотрелась в wiki или pdf после ее создания. Я должен иметь возможность изменять цвета, размеры шрифта, макеты и т.д.

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

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

Я обнаружил, что Doxygen может все это делать. Наш рабочий процесс следующий:

1. Разработчик вносит изменения в код

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

3. Мы нажимаем кнопку сгенерировать

Затем Doxygen извлечет всю XML-документацию из кода, отфильтрует ее, чтобы включать только те классы и методы, которые нам нужны, и применит стиль CSS, который мы предварительно создали для этого. Наш конечный результат — это внутренняя wiki, которая выглядит так, как мы хотим, и не требует редактирования.

Дополнительно: У нас есть все наши проекты в различных репозиториях git. Мы переносим все это в одну корневую папку и создаем документы из этой корневой папки..

Было бы интересно узнать, как другие автоматизируются еще больше ..?

1. Кто платит за документацию и почему? (достаточно ли стабильна система, добавляет ли она достаточную ценность)
2. Кто собирается это прочитать и почему она не использует более эффективный канал связи? (если правильно, в основном расстояние по времени / месту)
3. Кто будет поддерживать ее в актуальном состоянии.
4. Когда вы собираетесь ее уничтожить? (Автоматически, если она не была прочитана или обновлена за последние три месяца?)

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

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