プログラム理解のための 付加注釈 DocumentTag の提案 ○田中昌弘，石尾隆，井上克郎（大阪大）

発表概要 付加注釈DocumentTagの提案・実装 発表の流れ プログラム中の識別子に対して記述する注釈 注釈伝播 関連する識別子にも同一の注釈を付加 プログラム理解の作業効率を向上 発表の流れ 背景 DocumentTag・注釈伝播の提案 実験・評価

[1] ジョシュア・ブロック(著)、柴田芳樹(訳) 『Effective Java 第2版』 背景 オブジェクト指向プログラミング [1] デザインパターンなどを用いた効果的な導入 熟練者がまとめたオブジェクト指向プログミングの向けの設計上の問題解決法のカタログ モジュール性の向上 実装の詳細に依存しないモジュール間の処理が可能 再利用性の向上 クラスを追加する機能拡張が容易 [1] ジョシュア・ブロック(著)、柴田芳樹(訳) 『Effective Java 第2版』 ピアソン・エデュケーション、2008年

問題点 ソースコード上の検索・移動の負担が増大 識別子の役割を理解するには，関連する識別子を調べる必要がある 変数の型となるクラス メソッドの戻り値・引数・例外の型となるクラス 親クラスとなるクラス 複数のクラス間を移動・読解する必要がある [2] ツールによる支援が必要 [2] [2] N. Wilde et al., Maintenance Support for Object-Oriented Programs. IEEE TSE, Vol.18, No.12, pp.1038-1044, 1992.

付加注釈DocumentTagの提案 識別子に対して開発者が記述する注釈 注釈伝播により関連する注釈が参照可能 変数，メソッド，クラス 識別子の仕様や使用例，バグレポートなどを記述 注釈伝播により関連する注釈が参照可能 クラス，インタフェース， 列挙型，アノテーション フィールド，仮引数，局所変数 メソッド，コンストラクタ 識別子が出現している箇所で同じ注釈を参照 開発者が識別子に対して注釈を記録 Ｌｉｓｔ リスト構造の総称型

関連する識別子に対しても注釈が付加される 注釈伝播の例 注釈を記録 関連する識別子に対しても注釈が付加される 開発者 関連する注釈も参照可能 注釈を参照 lineElementList エディタ内の各行の情報を記録するリスト （型） List リスト構造の総称型

注釈伝播ルール 変数への注釈伝播 メソッドへの注釈伝播 クラスへの注釈伝播 変数宣言の型 → 変数 変数初期化子に出現する識別子 → 変数 戻り値・仮引数・例外の型 → メソッド 親クラスのオーバーライドされたメソッド → メソッド 同一クラスでオーバーロードされたメソッド → メソッド クラスへの注釈伝播 親クラス → クラス

変数への注釈伝播 変数宣言の型 → 変数 （1/2） 変数の型を調べる作業負担を軽減 lineElementList （型） List 注釈を記録 開発者 注釈を参照 lineElementList エディタ内の各行の情報を記録するリスト （型） List リスト構造の総称型

変数への注釈伝播 変数初期化子に出現する識別子 → 変数 （2/2） 初期化子内で構文木上最初に出現する識別子 変数の実際の型や値の意味を調べる負担を軽減 開発者 注釈を記録 注釈を参照 lineElementList エディタ内の各行の情報を記録するリスト （初期化）ArrayList 配列のリスト構造を生成

注釈伝播ルール 変数への注釈伝播 メソッドへの注釈伝播 クラスへの注釈伝播 変数宣言の型 → 変数 変数初期化子に出現する識別子 → 変数 戻り値・仮引数・例外の型 → メソッド 親クラスのオーバーライドされたメソッド → メソッド 同一クラスでオーバーロードされたメソッド → メソッド クラスへの注釈伝播 親クラス → クラス

（引数）IProgressMonitor （例外）JavaModelException メソッドへの注釈伝播 （1/3） 戻り値・仮引数・例外の型 → メソッド メソッドの役割を理解する作業を効率化 注釈を記録 開発者 getAttachedJavadoc Javadocをソースから取得 （型）String 文字列を扱うクラス 注釈を参照 （引数）IProgressMonitor 進捗バーを管理するクラス （例外）JavaModelException Java要素への操作の例外

メソッドへの注釈伝播 親クラスのオーバーライドされたメソッド → メソッド （2/3） メソッド間の継承関係を把握した理解が可能 注釈を記録 開発者 Formatterクラス 注釈を参照 format() LogFormatterクラス クラス名@メソッド名：ログの形式で出力する （オーバーライド）format() 出力するログの形式を定める

（同名）ArrayList(Collection) メソッドへの注釈伝播 （3/3） 同一クラスでオーバーロードされたメソッド → メソッド 類似した処理を行うメソッドから補間理解が可能 開発者 注釈を記録 ArrayList() 配列リストを生成 注釈を参照 （同名）ArrayList(Collection) 引数を配列構造に変換生成 （同名）ArrayList(int) 配列の初期サイズを指定

注釈伝播ルール 変数への注釈伝播 メソッドへの注釈伝播 クラスへの注釈伝播 変数宣言の型 → 変数 変数初期化子に出現する識別子 → 変数 戻り値・仮引数・例外の型 → メソッド 親クラスのオーバーライドされたメソッド → メソッド 同一クラスでオーバーロードされたメソッド → メソッド クラスへの注釈伝播 親クラス → クラス

OverloadedMethodProp.. クラスへの注釈伝播 直接の親クラス → クラス クラス間を横断する作業負担を軽減 開発者 注釈を記録 注釈を参照 OverloadedMethodProp.. オーバーライドに基づく注釈伝播を行うクラス PropagationRuleが直接の親クラス PropagationRuleが直接の親クラス （親）PropagationRule 注釈伝播ルールを指定するインターフェース

注釈伝播ルール 変数への注釈伝播 メソッドへの注釈伝播 クラスへの注釈伝播 変数宣言の型 → 変数 変数初期化子に出現する識別子 → 変数 戻り値・仮引数・例外の型 → メソッド 親クラスのオーバーライドされたメソッド → メソッド 同一クラスでオーバーロードされたメソッド → メソッド クラスへの注釈伝播 親クラス → クラス

Eclipseプラグインとして実装 エディタ上でカーソル位置に ある識別子の注釈 関連する注釈を同時に参照できる

適用実験 DocumentTagを用いた保守作業を実施 作業対象：Eclipseプラグインのソースコード 被験者A，B，C，Dが拡張課題a，bを行う 注釈伝播の有効・無効と課題の順序で作業時間を比較 課題終了後にアンケートの回答を集計 DocumentTagを用いる利点・改善点 各作業課題の中で時間のかかった作業（時間順） プログラム理解・コーディング・デバッグなど5項目

実験結果 有効に活用された注釈伝播（アンケートより） 親クラス → クラス 戻り値・仮引数・例外の型 → メソッド 保守作業を行った被験者 作業時間（分） 有効 無効 A （課題a：有効．課題b：無効） 131 77 B （課題b：有効．課題a：無効） 91 98 C （課題a：無効．課題b：有効） 63 87 D （課題b：無効．課題a：有効） 45 165 平均作業時間 82.50 106.75 有効に活用された注釈伝播（アンケートより） 親クラス → クラス 戻り値・仮引数・例外の型 → メソッド

考察 注釈伝播による平均作業時間の短縮 操作性の改善点 表示されうる注釈数の問題 関連する注釈の同時参照が要因 親クラス → クラス 戻り値・仮引数・例外の型 → メソッド 操作性の改善点 関連する注釈を参照するまでの操作を簡略化 表示されうる注釈数の問題 メソッドの場合で平均約3.75，最大84 （Eclipse 3.4 のソースコードを対象．全識別子に注釈を1つ付加）

まとめ 付加注釈DocumentTagの提案 注釈伝播の効果を適用実験で評価 今後の課題 識別子に対して記述する注釈 注釈伝播により関連する識別子に注釈が伝わる 注釈伝播の効果を適用実験で評価 関連する注釈の同時参照により作業時間の短縮 今後の課題 多数の注釈が伝播されうる問題への対処 操作性の改善

関連研究 ソースコード上の移動を支援 （1/2） 開発者が注釈を記入 一覧に登録される このような問題を対処するために関連研究では，その断片化したソースコードの移動を支援するというツールがあります． 小さいですが，エディタ内でのテキストの選択位置で，開発者が，右クリックしてタグの作成を選択して， 注釈を記入すると，それが，この下のビューで一覧に追加されます． そして，この一覧の項目をダブルクリックなどで選択すると，タグとして登録したファイルと位置に瞬時に移動できます． これによってソースコード上の移動がスムーズになったのですが，問題として， タグとして登録したタグが，ソースコード上の別の場所で活かされないという問題があります． 例えばメソッドについて選択した注釈は，そのメソッドが呼び出されている場所でも表示できるようにしたいということなどです． M.-A. Storey et al., How Programmers can Turn Comments into Waypoints for Code Navigation. ICSM 2007, pp.265-274.

関連研究 Javadoc （2/2） 開発者がクラス・メソッド・フィールドに対する注釈 ソースコード中にコメントとして記入 開発者間で注釈が共有できる 開発環境を利用すれば同一の識別子で注釈の参照が可能 ソースコードを編集できない場合がある APIドキュメントや，運用中のシステムのソース このような問題を対処するために関連研究では，その断片化したソースコードの移動を支援するというツールがあります． 小さいですが，エディタ内でのテキストの選択位置で，開発者が，右クリックしてタグの作成を選択して， 注釈を記入すると，それが，この下のビューで一覧に追加されます． そして，この一覧の項目をダブルクリックなどで選択すると，タグとして登録したファイルと位置に瞬時に移動できます． これによってソースコード上の移動がスムーズになったのですが，問題として， タグとして登録したタグが，ソースコード上の別の場所で活かされないという問題があります． 例えばメソッドについて選択した注釈は，そのメソッドが呼び出されている場所でも表示できるようにしたいということなどです． D. Kramer., API documentation from source code comments: a case study of Javadoc. SIGDOC 1999, pp.147-153.

メソッド名に対する 伝播元となりうる識別子の数 Eclipse 3.4 の ソースコードから抽出

学習効果による影響 課題1回目，2回目で作業時間が大きく異なる

学習効果による影響

学習効果による影響

利点・改善点