- PR -

更新履歴のコメント方法

1
投稿者投稿内容
きよ
常連さん
会議室デビュー日: 2002/03/27
投稿数: 21
投稿日時: 2002-05-07 12:29
いつもお世話になっております。

クラスに関するコメントの中に
@versionを使ってプログラムのバージョンを
記述したりしますが、
プログラムの更新履歴（更新日、更新者、更新内容）はどのように
記述するのが一般的なのでしょうか。
これに対して規定されたjavadocのタグ（？）は存在しないのでしょうか。
現在は次のように更新履歴（更新日、更新者、更新内容）を
記述しています。
@version 2002/03/07 高橋 新規メソッドgetNameを追加。
@version 2002/05/07 高橋 メソッドgetEmailを削除。

よろしくお願いします。
miki
大ベテラン
会議室デビュー日: 2001/09/21
投稿数: 174
お住まい・勤務地: 東京都八王子市
投稿日時: 2002-05-07 13:15
ツールを使うのが一般的ではないでしょうか。CVSやSourceSafeなどのソース管理ツールを使えば、履歴情報をソースに自動的に展開することが可能です。

CVSのキーワード置換:
http://www.sodan.org/~penny/vc/cvs-ja_12.html#SEC98

たとえば、CVSでは各ファイルのリビジョン番号を$Revision$を指定した箇所に埋め込みます。
これを利用してjavadocのversionタグに次のようにリビジョン番号を埋め込むことが可能です。

@version $Revision: 1.3$

更新履歴をjavadocに書いている例を私は見たことがありません。
更新履歴については、ユーザは知る必要が無いのでソースコメントとして書くのが適当では。
CVSの例では、$Log$をあらかじめコメントに書いておけば次のようにCVSの登録時にログが自動的に追加されていきます。

//　$Log: Sample.java,v $
//　Revision 1.1.1.1 2002/05/07 12:00:00 miki
//　initial import into CVS

でも、更新履歴に関してはCVSを見ればわかるし膨大な量になるので私は使いません。





miki
大ベテラン
会議室デビュー日: 2001/09/21
投稿数: 174
お住まい・勤務地: 東京都八王子市
投稿日時: 2002-05-07 13:33
> 更新履歴をjavadocに書いている例を私は見たことがありません。

訂正します。見たことがあったのに気づいていませんでした。
ちょっと確認してみたら、他人のコードで次のような例がすぐに見つかりました。
一般的かどうかはわかりませんが、HTMLタグを使うという方法もあるという一例です。

コード:
/**
 * ...
 * <p><b>Revisions:</b>
 * <p><b>20020507: miki</b>
 * <ul>
 *   <li>ｘｘｘを追加した</li>
 * </ul>
 * ...
 */

きよ
常連さん
会議室デビュー日: 2002/03/27
投稿数: 21
投稿日時: 2002-05-07 15:04
mikiさん
いつも返信ありがとうございます。

> ツールを使うのが一般的ではないでしょうか。
> CVSやSourceSafeなどのソース管理ツールを使えば、
> 履歴情報をソースに自動的に展開することが可能です。
なるほど。
今、WinCVSをインストールしてみました。
バージョン管理ツールについて無知なため、
これから勉強します。
※Microsoft Visula SourceSafeの価格を調べてみたのですが、
　オープン価格ということで見つけることができませんでした。
　ご存知の方いらっしゃいましたら教えてください。
　数万円くらいで買えるのかな？

ありがとうございました。
miki
大ベテラン
会議室デビュー日: 2001/09/21
投稿数: 174
お住まい・勤務地: 東京都八王子市
投稿日時: 2002-05-07 15:20
>今、WinCVSをインストールしてみました。

私もWindows上ではWinCVSに日本語パッチを当てたものを使っています。
グラフィカルにリビジョンのツリーが見れるのが便利です。

SourceSafeも使ったことがありますが、JavaのオープンソースプロジェクトがほとんどCVSベースなこと、IDEとの連携等を考えると、これから始めるならCVSの方をお勧めします。
もちろん、Windows開発に特化してしていてJNI等でWindows dllのソースも含めたい、Windows製品と連携させたいというならSourceSafeの方が便利でしょう。
1

スキルアップ／キャリアアップ（JOB@IT）