- - PR -
アノテーションを設計書に記載する方法
1
| 投稿者 | 投稿内容 | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
投稿日時: 2006-09-10 10:40
表題の通りなんですが、
アノテーションを設計書に記述する時、 どのようにされてますでしょうか？ 宜しくお願いします。 やっぱり、JavaDocで終わらせるのがBetterなんですかねぇ・・・？ [編集] 最終行追加 [/編集] [ メッセージ編集済み 編集者: るぱん 編集日時 2006-09-10 10:48 ] | ||||||||||||
|
投稿日時: 2006-09-10 21:12
アノテーションを設計書に記述？ 何か独自アノテーションでも作ってらっしゃるんですか？ 設計書に記述しないといけないようなアノテーションって 何を想定されているのですか？ | ||||||||||||
|
投稿日時: 2006-09-10 23:56
関数定義書やらモジュール定義書みたいな、
コボラーが喜びそうな仕様書を要求されたら、 それに合わせてドキュメントを作りますが、 私は大体Javadocで完結させます。 クラス関係の仕様書とかはJavadocに凝縮して、 設計書を別で作るということは、もう辞めましたね。 IDEと連携させることも考えると、 Javadoc中心で行くほうが何かと都合がいいので。 アノテーションに限った事じゃないですが、 大体これで押し切っています。 | ||||||||||||
|
投稿日時: 2006-09-11 10:11
JBossSeamやったんですけどね、
SessionScopeとPage（Request）Scopeの間にConversasionalScopeってのがあって、 ショッピングカートに対応するらしいです。 StatefulSessionBeanのオブジェクトの処理開始・終了に @Begin、@Endってのをつけて、 ショッピングカートに手続き開始・終了をメソッドとして持たせてたんですね。 @In@Outとかもあるんですけどね。 こういうのは、システム全体で統括する必要があると思います。 大規模でこういったアノテーションをつける場合、 いったいどういう規約で定めたものかと思うわけですよ。 標準アノテーションではないので、 直接それがどうこうっていう類の話ではないと思います。 メタアノテーションをシステム全体で定義した場合は、 それはやはり記述しなければならないと思うんですね。 なので、汎用的に、アノテーションを管理する必要が いつかどこかのタイミングで出てくるのではないかなんて思っています。 マーカーアノテーションだとしても、システム全体で整合を取るのであれば、 設計書には記載するべきだと思うのです。 JavaDoc以外の設計書って言うよりも、 外部設計書の一部の基盤提供になりそうな部分に記載しておくべきもの と言う認識なのですが、 そのときに、アノテーションをどのように記載してるのかが 気になりました。 | ||||||||||||
|
投稿日時: 2006-09-11 10:20
私の認識も正にそれでして。 javadocはメソッドやフィールドといった実装レベルでの仕様を 記述するには向いているとは思うのだけども、 それらと同列に記述しなければならないようなアノテーションって どうも想像がつかなかったので。 アノテーションから設定ファイルなどを自動生成しているような ケースではjavadocレベルで記述することもあるのかもしれませんが 今のところそういう事態に遭遇していないのでよくわからない…。 大局的に見ないといけないものはどこか別途に…というか、 いっそ仕様書を自動生成できるようにしておけばいいのかも。 | ||||||||||||
|
投稿日時: 2006-09-11 11:17
るぱんです。
標準アノテーション以外のアノテーションは１箇所で使うのであれば 標準アノテーション準拠で問題ないと思います。 ただ、複数箇所で使うことになった瞬間に 設計思想とぶつけることになると思うので、 標準でないものは、標準でないがゆえに設計書に残す必要があると思っています。 nagiseさんの話から推測すると、 問題があります。 １．外部設計書が実装にあわせてインクリメンタルになると言うことが問題です。 詳細設計と実装でインクリメンタルは理解できますが、 外部設計書がインクリメンタルになること自体だし、 そんなプロジェクト関わりたくないです。 外部設計書は骨格を現すわけですから、骨格がずれるので問題だと思います。 ２．実装から設計書に〜っていう話は理解できますが、 実装に左右されすぎて、 良いアーキテクチャーを放棄してしまうことにつながるので、 基本は設計書ありきというスタンスは崩したくないのです。 | ||||||||||||
|
投稿日時: 2006-09-11 11:59
ここは同意見です。 javadocは概要というか骨格というか大局的な設計を書くには向かない。 いや、パッケージのドキュメントレベルあたりにでも書いたら それはそれなんでしょうが、基本的には向かないと思っていますね。
「いっそ仕様書を自動生成できるようにしておけばいいのかも」 のくだりでしょうか。 実装と仕様書がブレないという点では利点があるものの、
と指摘された点そのものがデメリットであると認識しています。 ただ、仕様書があり、実装があるものの、ソース（実装）が メンテナンスされても仕様書が同期してメンテされていない という状況のプロジェクトに置いて（その時点でやりたくないかもしれませんが） 結局のところ、仕様の正となる代物が仕様書ではなくソースになってしまっている。 そんな状況を想定するのであれば、「以下のソースに関しては〜をする」 という類の仕様の記述に対して、ソース側からの自動生成というのは それなりの利があると思っています。 ただし、自分のこの主張は「仕様書が仕様の正とされていない状況で」 という前提の下の話なので、前提が覆れば、つまり 「仕様書が仕様の正とされている状況」においてはこんな方法論は 論外だと思っています。 # そんな前提のプロジェクトばかりやっていますが 
| ||||||||||||
|
投稿日時: 2006-09-11 12:25
うん。まったく同意ですね。 「仕様書が仕様の正とされている状況」について １．現在では亜流とか傍流とかに近い位置づけではありますが、 方法論として存在しています。 ２．ただし、正攻法と定義されているべきもの と言う視点で見ています。 プロジェクト開始当初に何らかの技術的なリードをする立場が多いもので、 こういう場合、どうしたものかなぁ？ と言う風に思っています。 技術が出てきて設計書のテンプレを考えるっていうのは泥縄かもしれません。 そもそも、仕様書に落としこめるように技術を開発すればいいのだが・・・ んな事言ったって、オープンソースやベンダーのパッケージ開発部隊の メンバーじゃないんで、んな事言うならお前がやれ・・・だとは思いますが。（汗 | ||||||||||||
1
スキルアップ／キャリアアップ（JOB@IT）
Copyright © ITmedia, Inc. All Rights Reserved.
著作権はアイティメディア株式会社またはその記事の筆者に属します。
当サイトに掲載されている記事や画像などの無断転載を禁止します。
著作権はアイティメディア株式会社またはその記事の筆者に属します。
当サイトに掲載されている記事や画像などの無断転載を禁止します。