Java Project Documentation

Question

Javaプロジェクトを文書化する必要があります。私はC＃プログラマーとシステムアナリストです。しかし、私はJavaに慣れていません。

私はSVNからディレクトリをチェックアウトしました。

これらのディレクトリは、プロジェクトの定義に必要なソースディレクトリ、WEB-INFおよび他のファイル、クラスパスなどが含ま

私は、ファイルは、基本的に次の三つのカテゴリーのいずれかに属していることを理解し

1. パッケージの構造（.Java）に基づいたソースコードファイル/ディレクトリ
2. プロジェクト定義、コンパイラ設定などに必要なディレクトリ/ファイル
3. 必要なファイルr展開。

プロジェクトは、Tomcatでホストされるように設計されたEclipseベースのプロジェクトです（ほとんどのJavaプロジェクトがそうです）。今

は、私は、3つの異なる文書

1. ソースコードなど
2. ファイル&ディレクトリの目的を説明した書面を説明する文書にプロジェクト全体を文書化することを決定した上記の情報を与えることコンパイラ設定、プロジェクト定義などに必要です
3. デプロイメントディレクトリ構造について説明するドキュメント。

また、上記の1-3の3つのセクションで1つのドキュメントを作成することもできます。

は今、質問

1. は、これは正しいアプローチですか？
2. 私が従うことができる他の方法論はありますか？
3. あなたが任意の追加情報が使用されるであろう。このアプローチ

に追加することができます任意の他の提案などがあります。事前に

おかげトン

Answer 1

あなたは正しい軌道にいると思います。このプロジェクトでは、3つのドキュメントはこのアプリケーションが何であるか、および/アクセスUT、それを起動する方法を記載した書面を含ん

1. ユーザードキュメント を必要と対処する必要があります。

2. 開発ドキュメント これには、少なくともJavadoc、ソースコードのディレクトリ構造、ビルドプロセス（プロジェクトのコンパイル方法）、コンパイラ時間依存性、開発標準、データベースの設定方法開発のために、リポジトリからソースコードを入手する方法について説明します。これらは、他の人があなたのプロジェクトで働くために必要な最小のものです。また、プロジェクトの複雑さが増すにつれて、システム内の一般的なタスク（たとえば、「特定の操作の監査証跡を残す方法」、「ログフレームワークを使用する方法」、どのように例外を管理するかなど）、主要なドメインクラスとそれらの関係の説明。データベースを使用しており、データベーススキーマがドメインクラスと一対一でない場合は、スキーマのドキュメントを追加します。

3. デプロイメントドキュメント これは基本的にアプリケーションのインストールマニュアルで、実行するために必要な手順を説明しています：TomcatにWARを置く、データベースに対してスクリプトを実行する、変更する必要がある設定ファイルなどなど。

ご覧のとおり、2つの部分を既に扱っています。小さくて簡単に始め、必要に応じて残りの部分を追加します。

また、組織の文書化基準があるかどうかを確認するのに役立ちます。

Answer 2

はJavadocsリンクをお試しください。適切な計画で書かれていれば、上記のすべてのポイントに対処します。

Answer 3

等ソースコードを説明する文書

はい。あなたの読者が、プロジェクトがなぜ書かれたのか（なぜこのプロジェクトが作成されたのか）とプロジェクトの全体的なアーキテクチャーに精通しようとしていたかのように、これにアプローチしてください。

ソースクラスのJavadocは、各クラスの機能を説明する必要があります。あなたのドキュメントは、チュートリアルのように、Javadocを結びつけるべきです。

コンパイラ設定に必要なファイル&ディレクトリ、プロジェクト定義など

はいの目的を説明する文書。

展開ディレクトリ構造について説明するドキュメント。

あなたのビルドスクリプトが行うことだと思います。おそらく私はあなたがこの文書が期待することを理解していないでしょう。

これが初めてでない限り、あなたがこのアプローチに

を追加することができます任意の他の提案などは、開発グループの誰もが、Javaプロジェクトを文書化しており、他の文書があるはずあります。彼らが何をしたかを見てください。

あなたが最初の人なら、これは良いスタートだと思います。私は最初の文書に最も興味があります。あなたの新しいプログラマーは2番目の文書を望みます。