翔泳社の公式通販SEshopは全国送料無料!
ヘルプ 新規会員登録 ログイン
SEshop

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

佐藤 竜一(著)

商品番号
119480
販売状態
品切れ
納品形態
宅配便にてお届け
発売日
2009年06月29日
出荷開始日
2009年06月30日
ISBN
9784798119489
判型
A5
ページ数
240
キーワード
プログラミング  Java

2,640円(税込)(本体2,400円+税10%)
送料無料

240pt (10%)
ポイントの使い方はこちら

初回購入から使えるポイント500円分プレゼント

現在、本商品は販売しておりません。

※1点の税込金額となります。 複数の商品をご購入いただいた場合のお支払金額は、 単品の税込金額の合計額とは異なる場合がございますので、予めご了承ください。

「ソースコードがドキュメント」 その意味を正しく理解している人が“使える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の実践ってことでここが一番書きたかったことなのかもしれないけど

関連商品

おうちで学べる Pythonのきほん

2,420円(税込)

2024.05.20発売

おうちで学べる Pythonのきほん【PDF版】

2,420円(税込)

2024.05.20発売

おすすめ特集

法人・教育機関のお客様へ

【法人・教育機関のお客様へ】新年度の大口注文・お見積りなど、お気軽にご相談ください

Webデザイン特集

デザインやコーディングなど、Webデザインに役立つスキルが身につく書籍を揃えました

生成AI特集

テキスト生成、画像生成、動画生成など、生成AI活用のスキルが身につく本をご紹介

新社会人におすすめの本

新社会人の役に立つスキルが身につく本。ビジネスパーソンとしてスタートダッシュを切ろう!

プログラミング教育の本

小学校から必修化!人気の『ルビィのぼうけん』ほかプログラミング教育の本はこちら

翔泳社のセミナー・講座

開発・ビジネス・マーケティング・EC運営・営業支援など、幅広いジャンルの講座を開催

特集をもっと見る