エンジニアのためのJavadoc再入門講座(佐藤 竜一)|翔泳社の本
  1. ホーム >
  2. 書籍 >
  3. エンジニアのためのJavadoc再入門講座

エンジニアのためのJavadoc再入門講座


形式:
書籍
発売日:
ISBN:
9784798119489
定価:
2,640(本体2,400円+税10%)
仕様:
A5・240ページ
カテゴリ:
プログラミング・開発
キーワード:
#プログラミング,#開発環境,#開発手法,#Web・アプリ開発

「ソースコードがドキュメント」 その意味を正しく理解している人が“使えるJavadoc”を書ける人。

Javadocとは、JavaのソースコードからHTML形式のAPI仕様書を生成するためのテクノロジーです。多くのJavaプログラマは日常的にJavadocを利用しており、その記述方法も広く知られています。しかし、実際の開発現場で“使えるJavadoc”を目にする機会はほとんどどありません。記述はされているものの、意味のある内容だとは到底思えないようなJavadocが氾濫しているのです。
そこで本書では、優れたJavadocから得られる多くのメリット―たとえば、設計の効率化、再利用性の向上、学習コストの低下―を具体的に示し、これに必要となる知識や書き方についてを簡潔にまとめました。
Java開発に携わる方はもちろん、すべてのアーキテクト/プログラマにとって必読の1冊です。

第1章 なぜJavadocを使うのか

1.1 プログラムを説明するドキュメントはなぜ必要?
  1.1.1 ソースコードがドキュメント?
  1.1.2 「コードを読め!」と言われても・・・・・
  1.1.3  仕様を書くにはExcelが必要?
1.2 Javadocを使って仕様を書く
  1.2.1 Javadocとは何か?
  1.2.2 ドキュメンテーションコメントには何を書くのか?
  1.2.3 ドキュメンテーションコメントがもたらすメリット
  1.2.4 ドキュメンテーションコメントでは書き表せないこと
1.3 よいコメント、悪いコメント
  1.3.1 コードの翻訳に意味はない
  1.3.2 ドキュメンテーションコメントを書くのが難しい理由
1.4 わかりやすい仕様を書くためには

第2章 Javadocの基礎

2.1 ドキュメンテーションコメント
  2.1.1 ドキュメンテーションコメントとして認識されるコメント
  2.1.2 Javadocタグの存在
  2.1.3 HTMLとしての記述
2.2 ドキュメンテーションコメントを文章として仕上げる
  2.2.1 テキストレベルでの整形はやめよう
  2.2.2 段落のマークアップ
  2.2.3 箇条書きの実現方法
  2.2.4 特殊な文字を簡単にエスケープする
  2.2.5 表を記述する
  2.2.6 視覚系要素の使い方
2.3 ハイパーリンクの設定方法
  2.3.1 他のクラスやメソッドに対してリンクを張る
  2.3.2 メソッドへのリンクの貼り方
  2.3.3 リンクに表示される文字列を普通のフォントにする
  2.3.4 静的フィールド値の参照
  2.3.5 関連項目には@seeでリンクを設定する

第3章 メソッドやフィールドに対するドキュメンテーションコメントの記述方法

3.1 「メソッド名の日本語訳」はいらない!
3.2 メソッドに対するドキュメンテーションコメントの基本
  3.2.1 引数に対するドキュメンテーションコメント
  3.2.2 返却値に対するドキュメンテーションコメント
  3.2.3 例外に対するドキュメンテーションコメント
3.3 引数/返却値/例外の説明として記述すべきこと
  3.3.1 引数に対する説明の記述方法
  3.3.2 返却値に対する説明の記述方法
  3.3.3 例外に対する説明の記述方法
3.4 メソッドの主説明に記述すべきこと
3.5 フィールドに対するドキュメンテーションコメント
3.6 説明が省略された場合のデフォルトを決定しておく
  3.6.1 典型的な特異値の省略
  3.6.2 booleanを返すメソッドではtrueのケースだけを書く
  3.6.3 setter/getterに対するドキュメンテーションコメントの書き方
3.7 可視性とドキュメントメンテーションコメント
  3.7.1 privateに対するドキュメンテーションコメントは不要
  3.7.2 protectedに対しては継承を意識して書く
  3.7.3 publicに対するドキュメンテーションコメントは責任が重い
3.8 継承とドキュメンテーションコメント
  3.8.1 メソッドコメントの自動継承
  3.8.2 継承元のドキュメンテーションコメントを引用する

第4章 クラスに対するドキュメンテーションコメントの記述方法

4.1 クラスに対するドキュメントの存在意義
4.2 インターフェースのドキュメントに求められるもの
4.3 クラスのドキュメントに求められるもの
4.4 継承を意識した記述
  4.4.1 抽象メソッドにおける実装要求
  4.4.2 オーバーライド可能なメソッドの自己利用
  4.4.3 骨格実装の扱い
  4.4.4 サブクラスでの差分の表現
4.5 特殊なクラス
  4.5.1 アノテーション
  4.5.2 列挙型
  4.5.3 例外

第5章 Javadocのその他の機能

5.1 パッケージに対するドキュメンテーションコメント
5.2 シリアライズ可能なクラスに対するドキュメンテーションコメント
  5.2.1 シリアライズ対象フィールドを示す@serialタグ
  5.2.2 serialPersistentFieldsを利用したシリアライズ対象フィールドの指定
  5.2.3 シリアライズ/デシリアライズの方法をカスタマイズした場合
  5.2.4 シリアライズの対象となる情報は別途記載しておく
5.3 クラスやパッケージのバージョン情報
  5.3.1 作者の示し方
  5.3.2 現在のバージョンの示し方
  5.3.3 新しい機能を追加したバージョンの示し方
5.4 ドキュメンテーションコメントにおけるその他の留意点
  5.4.1 先頭の一文に全力を傾ける
  5.4.2 使うべきではないものを示す方法
  5.4.3 リンクを設定する上での注意点

第6章 Javadocを使ってAPI仕様書を生成する

6.1 API仕様書生成の基本
  6.1.1 ソースコードの格納場所の指定
  6.1.2 API仕様書生成対象とするパッケージの範囲の指定
  6.1.3 ソースコード中で使われているクラスの検索場所の指定
  6.1.4 出力先の指定
  6.1.5 最終的なコマンドラインイメージ
6.2 MavenやAntを使ってAPI仕様書を生成する
  6.2.1 MavenによるAPI仕様書の生成
  6.2.2 AntによるAPI仕様書の生成
6.3 API仕様書の使い方
  6.3.1 API仕様書の画面構造
  6.3.2 API仕様書のディレクトリ構造
  6.3.3 API仕様書に盛り込めないもの
6.4 出力方法のカスタマイズ
  6.4.1 ドキュメンテーションコメントに出力する可視性の指定
  6.4.2 クロスリファレンス的な利用
  6.4.3 バージョンや作者の出力
  6.4.4 タイトルや著者権情報を埋め込む
  6.4.5 各種の出力の抑制
6.5 エンコーディングと国際化
  6.5.1 ソースコードのエンコーディング
  6.5.2 API仕様書のエンコーディング
  6.5.3 API仕様書の言語を決める
  6.5.4 エンコーディング指定のまとめ
6.6 外部のAPI仕様書へとリンクを設定する
  6.6.1 API仕様書生成時にほかのAPI仕様書を参照する
  6.6.2 オフラインでもほかのAPI仕様書へのリンクが設定できるようにする
  6.6.3 2つのAPI仕様書の間で相互参照を生成する
  6.6.4 Ant/Mavenでの利用例
6.7 ソースファイルへのリンクを生成する
6.8 概要ページのカスタマイズ
  6.8.1 概要ページにドキュメントを追加する
  6.8.2 概要ページのパッケージ一覧をグルーピングする
6.9 その他の特筆すべき機能
  6.9.1 API仕様書で利用するCSSファイルを指定する
  6.9.2 @serialタグの利用を確認する
  6.9.3 索引の分割

第7章 アノテーションによる仕様記述

7.1 再び「契約による設計」
7.2 Contract4J5を使って契約を明確化する
  7.2.1 Contract4J5とは
  7.2.2 Groovyによる契約の記述
  7.2.3 条件を表現するアノテーション
  7.2.4 Contract4J5の特別なキーワード
7.3 Contract4J5の実例
  7.3.1 Contract4J5の入手とインストール
  7.3.2 対象のクラスに@Contractを付与する
  7.3.3 事前条件の記述
  7.3.4 事後条件の記述
  7.3.5 不変条件の記述
7.4 Contract4J5を使ったプログラムを動かしてみる
  7.4.1 AspectJのインストール
  7.4.2 ajcによるコンバイル
  7.4.3 契約が付与されたクラスの実行例
  7.4.4 API仕様書の生成
7.5 契約記述の詳細
  7.5.1 事前条件でオブジェクトの状態をチェックする
  7.5.2 事後条件でメソッドの結果を検証する
  7.5.3 キーワード$oldの制約
  7.5.4 継承と契約

本書は付属データの提供はございません。

お問い合わせ

内容についてのお問い合わせは、正誤表、追加情報をご確認後に、お送りいただくようお願いいたします。

正誤表、追加情報に掲載されていない書籍内容へのお問い合わせや
その他書籍に関するお問い合わせは、書籍のお問い合わせフォームからお送りください。

利用許諾に関するお問い合わせ

本書の書影(表紙画像)をご利用になりたい場合は書影許諾申請フォームから申請をお願いいたします。
書影(表紙画像)以外のご利用については、こちらからお問い合わせください。

追加情報はありません。
この商品の「よくある質問」はありません。
正誤表の登録はありません。

感想・レビュー

leather_sole さん

2009-08-24

文中だけでは抽象的だし(Java本体のJavadocなどを横に置いてみればいいけど)、contract4J5は案の定Javadocとは切り離されているし、一読すれば十分かな。

akagi_paon さん

2013-06-12

★★★

TUI さん

2009-10-22

Javadocに必ずしも依存しない汎用的は話の部分は折に触れて読み返すのがいいかな。最後のContract4J5の話はいらなかったような。まぁ、DbCの実践ってことでここが一番書きたかったことなのかもしれないけど