Help us understand the problem. What is going on with this article?

Web開発プロジェクトにおけるJavaDocの理想的な運用・使用方法考察2015.11

More than 3 years have passed since last update.

Web開発プロジェクトでのJavadocの運用方法について現時点(2015年11月)でどのように利用すべきか検討したのでまとめてみました。
実際は使用できるツールやサーバが限られるし、現状によってはいきなりJavadocを使用できないかもしれないので以下のすべてを設定できるかというと難しいのですが。
あくまで私見なのでもっといいツールや運用方法があればコメントください。

前提

  • JavaによるWeb開発
  • 構成管理ツールとしてchefを使用
  • インテグレーションツールとしてJenkinsを使用
  • プロジェクト管理ツールとしてredmineを使用
  • 単体テストではJUnitを使用
  • 内部結合テスト以降、テストではselenium, appiumを使用
  • 開発者のIDEとしてEclipseを使用

目的

  • 開発効率の向上
  • 納品ドキュメント作成工数の削減
  • 属人化の排除
  • 開発者のスキルアップの促進
  • 開発者の手抜き・抜け漏れの防止

構成管理者の設定

  • 出力文字コードの指定
    ソースコードの文字コードと合わせる事。良く忘れて文字化けするので。当然ant.xmlに設定しておいて開発者が意識せずに使えるようにしておく事。
    Javadocのオプションに以下を追加する。
    -encoding utf-8
    -charset utf-8


  • Javadocタイトル設定
    Javadocを表示するブラウザのタイトルバーに表示されるタイトルを設定
    Javadocのオプションに以下を追加する。
    -windowtitle HogeHogeプロジェクト

  • Javadocの先頭ページ(概要ページ)の設定
    Javadocの先頭ページ(概要ページ)にアプリケーションの説明、環境、バージョン情報等を持たせる。selenium等のテストの場合はテスト前提条件、観点等も記載する事。
    参照:Javadocの概要ページ設定

  • クラスパスmain以下のクラス図出力設定
    main以下のJavadocにはクラス図を自動で出力しておくと何気に見直した時に使い方の間違いに気づく時がよくある。デザインパターンを確認する場合にも役立つ。何より開発者がクラス図とコーディングの関係を学習するのでスキルアップにつながる。
    参考:Eclipse+APIvizでjavadocにクラス図を出力

開発者が実施する事

  • Javadocパッケージ概要説明
    Javadocのパッケージ先頭ページにパッケージの概要説明を持たせる。当然、main以下はそのパッケージの説明、test以下は何のパッケージの単体テストかの説明、selenium等のテストの場合はシナリオ別にパッケージを分けてシナリオの説明、前提条件、テスト観点を記載する。
    参照:Javadocの概要ページ設定

  • Javadocクラス/メソッド説明
    クラス説明は必須。packageメソッド以上のメソッド(他クラスから参照が可能なメソッド)は必須。privateメソッドは任意。
    クラスは一行コメント、作成者(@auther:生成したhtmlには表示しない)は必須。
    メソッドは一行コメント、パラメータ(@param)、戻値(@return)、スロー(@throw)は必須

  • selenium, appiumのシナリオ説明
    シナリオ、ケース毎にJavadocで説明を作成する。シナリオ番号、ケース番号はクラス名、メソッド名に付加し、スクリーンショットを出力している場合はスクリーンショットファイル名にシナリオ番号、ケース番号を付加して紐付けるようにする。

運用

  • 開発フェーズ以降のJenkinsを使用したクラスパスmain以下のJavadoc出力
    開発期間中は毎日Jenkinsで出力する。
    クラス図を一緒に出力する事。

  • クラスパスtest(単体テストソース)以下のJavadoc出力
    開発期間中は毎日Jenkinsで出力する。
    クラス図の出力は任意。

  • selenium, appiumによるテストプロジェクトのxmlリスト出力
    顧客の意向で結合テスト内容等はExcelでの提出を強制されるような場合は
      Javadoc⇒xml⇒Excel等のフォーマット
    と出力する必要がある。Jenkinsで定期的に実行。
    ここが一番手間。
    Excel等のフォーマットに取り込む際は、テスト結果も取り込めるようにしておく。seleniumとJavaDocの使用で内部結合テスト以降の工数はかなり削減できる。
    ※なぜかJavadocをxmlで出力するドックレットが見つからないので自作するしかないみたい。Doxygenだったらxml出力できるのでここだけDoxygen使って出力するか。
    また、xmlからExcel等のフォーマットに取り込むのは別途マクロ作成。Java等の開発で使用している言語使って直接ドキュメント出力するのも有りだけど他プロジェクトに応用が利くようにelectronとかC#でWindowsアプリ作った方がいいのかな。

  • Checkstyleの設定
    残念なことだが、コーディングが好きな開発者もJavadocは面倒くさがって書きたがらない人が多い。いくら手順化しても漏れてしまうことが多々ある。ということでCheckstyleにJavadocのチェックを入れる。
    Checkstyleはchefで配布するようにし、同様の設定でJenkinsで定期的にチェックする。
    参考(近日公開予定):[Eclipse CheckStyle サンプル]

  • redmineの設定
    Jenkinsで定期的に出力したJavadocをredmineのwiki等からリンクしておく。テスト関連のJavadocは生成したドキュメントをダウンロードできるようにしておく。他のドキュメント類も含めてredmineから全てリンクし一元管理する事が理想。

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした