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

翔泳社(出版社) , 佐藤竜一(著)

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

販売価格:¥2,592(税込)

送料無料 在庫あり

本体価格の10%をポイント還元(会員限定)

ほしい物リストに追加

「ソースコードがドキュメント」 その意味を正しく理解している人が“使える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 継承と契約

各種問い合わせは以下のリンクからご連絡ください

関連商品

入門HASKELLプログラミング

販売価格:4,104円(税込)

2019.07.31発売

絵で見てわかる量子コンピューターの仕組み

販売価格:2,786円(税込)

2019.07.10発売

作れる!学べる!Unreal Engine 4 ゲーム開発入門 第2版

販売価格:3,542円(税込)

2019.07.03発売

おすすめ特集

今月のクーポン

翔泳社の通販SEshopなら全品送料無料、ポイント還元、さらに毎月更新の割引クーポンでお得!

Python特集

【今からはじめるPython特集】おすすめ本を入門~上級までレベル別にご紹介!

情報処理教科書シリーズ

情報処理技術者試験におすすめの参考書「EXAMPRESS 情報処理教科書シリーズ」で最短合格!

アルゴリズムと数学の本

プログラマ脳を鍛える!エンジニアが読むべきアルゴリズムと数学の本特集。

【特集】翔泳社のロングセラービジネス書

初版刊行以来人気を集め続けている翔泳社のロングセラービジネス書をご紹介。

SQL/データベース関連本特集

初心者向けの入門書から、達人レベルの専門書まで!SQL/データベース関連おすすめ本特集。

特集をもっと見る