Документация по проектам Java

Question

Мне нужно документировать проект Java. Я программист на C# и системный аналитик. Но я новичок в Java.

У меня есть каталоги, извлеченные из SVN.

Эти каталоги включают в себя исходные каталоги, WEB-INF и другие файлы, необходимые для определения проекта, и т.д. Путь к классам

Я понимаю, что файлы по существу принадлежат одному из следующих трех категорий

1. Файлы исходного кода/каталоги, основанные на способе структурирования пакетов (.Java)
2. Каталоги/файлы, необходимые для определения проекта, настроек компилятора и т. Д.
3. Файлы, требуемые для r развертывание.

Проект (как и большинство проектов Java) - проект на основе Eclipse, предназначенный для размещения на Tomcat.

Теперь, дать вышеуказанную информацию, которую я решил задокументировать весь проект в трех различных документов

1. документ с изложением исходного кода и т.д.
2. документ, объясняющее цель файлов & каталогов, которые требуются для параметров компилятора, определений проектов и т. д.
3. Документ, который объясняет структуру каталога развертывания.

Или, альтернативно, я мог бы создать единый документ с тремя разделами, которые объясняют 1-3 выше.

Теперь вопросы

1. Является ли это правильный подход?
2. Есть ли какие-либо другие методологии, из которых я могу следовать или брать кредиты?
3. Есть ли какие-либо другие предложения и т.д., которые вы можете добавить к этому подходу

Любая дополнительная информация будет полезна.

Благодаря тонну заранее

Answer 1

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

1. документация пользователя Это включает документ о том, что приложение о, и как начать его/ет доступ.

2. Документация по развитию В нее входят как минимум Javadocs, описание структуры каталогов исходного кода, процесс сборки (то есть, как скомпилировать проект), временные зависимости компилятора, стандарты разработки, как настроить базу данных для разработки и как получить исходный код из репозитория. Это минимум, который вам нужно, чтобы заставить других работать в вашем проекте. Кроме того, по мере роста сложности проекта мне нравится составлять серию «How To» для общих задач в системе (например: «Как оставить контрольный журнал для данной операции», «Как использовать структуру ведения журнала», «Как управлять исключениями» и т. Д.), Описание основных классов домена и их взаимосвязь. Если вы используете базу данных, а схема базы данных не является точно одним-на-один с классами домена, я добавлю документацию схемы.

3. Документация по развертыванию Это руководство по установке приложения, описывающее любые шаги, необходимые для его запуска: включение WAR в Tomcat, запуск сценариев по базе данных, файлы конфигурации, которые необходимо изменить, и т. Д. И т. Д. ,

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

Это также помогает проверить, имеет ли ваша организация какой-либо стандарт документации.

Answer 2

Попробуйте Javadocs ссылку. Написано с надлежащим планированием, оно рассмотрит все ваши пункты выше.

Answer 3

документ объясняет исходный код и т.д.

Да. Подходите к этому так, как если бы ваш читатель был кем-то, кто пытался понять причины, по которым был написан проект (почему был создан этот проект), а также общую архитектуру проекта.

Javadocs в классах источников должен объяснить, что делает каждый класс. Ваш документ должен связывать Javadocs вместе, как учебник.

документ, объясняющий цель файлов & каталогов, которые необходимы для настройки компилятора, определения проекта и т.д.

Да.

Документ, который объясняет структуру каталога развертывания.

Я полагаю, что это то, что делают ваши скрипты сборки. Возможно, я не понимаю, чего вы ожидаете от этого документа.

Есть ли какие-либо другие предложения и т.д., которые вы можете добавить к этому подходу

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

Если вы первый, то я бы сказал, что это было хорошее начало. Меня больше всего интересует первый документ. Вашим новым программистам нужен второй документ.