プログラム説明書の読み書き

概要

Javaに限らず現代的なソフトウェアシステムでは他人様が作成したプログラム部品(Javaの場合，クラス群)を流用して開発を行います．適切に流用するためには部品の内容を理解しなければなりませんが， Javaでは標準的な説明書の書き方があります．まずはそれに慣れることが重要です．

次に，自分が作ったプログラム(クラス)の使い方や個々のソースの説明等を他人(および未来の自分)のためにかかないといけません．しかし，説明書書きはかったるい作業です．しかも，プログラムとは別のところに書かなきゃいけないとなると適当になることは必至です．
Javaではプログラム中の(ある程度の形式にのとった)コメント文から，プログラムの説明書き(HTML形式等)を自動的に抜き出す仕組み javadocが準備されています．

マニュアルを書く前に

詳細は後日話しますが， Java でのクラス，属性，メソッド名は以下の命名規則にしたがってください．尚，原則，英語の語句を用いてください．

クラスは名詞(句)で最初大文字，残りは小文字，そして語の区切りも大文字に．
例 ○ Student × student
例 ○ CodeGenerator × codegenerator
属性名は名詞(句)で，全部小文字，ただし語句の区切りは大文字．
例 ○ counter × Counter
例 ○ numberOfCodes × NumberOfCodes
メソッド名は動詞(句)で，全部小文字，ただし語句の区切りは大文字．
例 ○ notify(...) × Notify(...)
例 ○ getAge(...) × GetAge(...)
メソッド名の動詞(句)は，主語が当該クラス以外となるようにする．
○ Player.getName() 名前を得るのはPlayer以外 × Player.showHand() showの主語はPlayerなので不適切．

従わなくても文法的には間違っていないのですが，プログラムの読みやすさに影響します．

APIマニュアルの読み方

例えばStringクラスについて [HTML]
自作のプログラムについて: じゃんけん [HTML], 屋台 [HTML]

javadocの生成の仕方

注目しているプロジェクトが保存されているOS上のパスを一応確認しておきます．プロジェクトを選択して，右クリックで properties を選択して， Resource を押すと確認できます[JPG]．この例では，プロジェクト Noodle1 は OS上の D:\eclipse\420w\Noodle1\ に保存されていることがわかります．プロジェクトのフォルダはデフォルトでは， OSが指定する自身のユーザーデータ下の workspace フォルダの下だったと思います．
プロジェクトを選びExportを選択 [JPG]
Javadocを選択 [JPG]
Javadoc command の場所は初回は設定されていないので，図のように Configureボタンで選択してください [JPG]．
とりあえず全属性とメソッドを文書化したいのであればprivateを選択． (デフォルトはpublicのはず) 生成場所の指定も注意してください．
生成するページの種類はデフォルト(Use standard doclet)でいいでしょう [JPG]．もし，Destination が設定されていない場合，どこでもいいんですが，当該プロジェクト下の doc というフォルダがよいでしょう．
しばらく Next 押して， Configure Javadoc arguments for standard doclet にいきます． Select referenced ... は全選択でもいいのですが，少なくとも rt.jar だけは選択しておいたほうが便利です [JPG]．
しばらく Next 押して， Configure Javadoc arguments のところまでいきます [JPG]． Extra javadoc options で，以下を指定してください．
```
-encoding utf8
-docencoding sjis
```
Yes to All でいいです．
できたものはEclipse内からも参照できます (Macでは未確認) [JPG]
ま，ただのHTMLページですから，ブラウザで直接つついても見れます [HTML]

無論，Eclipse無しでも作れますが，詳細は他を調べてください．

javadocの書き方 (最低限)

共通事項

/** .... */ で囲む．開始の*が二つなのに注意．
クラスやメソッド，属性を使う側にたって必要十分な情報を与えること．

クラスについて

クラスがどんな役割を担うかわかりやすく説明．
@author クラスを作った人の氏名等．この授業では名前だけでなく学籍番号もかいてね．

属性について

属性の意味(役割)をわかりやすく説明．

メソッドについて

メソッドが何をするものなのかを解りやすく説明
@return 返り値が何が返るのかを説明．特に条件によってかわったりする場合についても念入りに．
@param 引数の意味を説明．特に引数の条件(例えばnullはダメとか負の数はダメとか)はちゃんと説明．

その他タグはいろいろ

リンク

練習として，教科書3章後半のじゃんけんサンプルでもやってみましょう [HTML]
グーグルでサクっと調べるのが一番いいかも・・・
Sunサイトのマニュアル APIの仕様 6 [HTML]
Sunサイトのマニュアル javadocについて [HTML]

本ページトップ | 戻る

更新