コメントの有効活用

前回の記事 でプログラム内のコメントについて、後任開発者のためにも手を抜かずしっかり記述することが重要だとまとめました。とはいっても、記述するにはそれなりの時間がかかります。せっかく書いたコメントですから有効に活用したいですよね。

ホップアップヘルプ

コメントを有効活用する上で効果的なのが、関数ヘッダコメントです。

8.x 以降のドミノデザイナーでは、関数やメソッドのカーソルをあてるとその関数の定義がポップアップヘルプとして表示されます。

この機能は、開発者自身が作成した関数でも有効となるのですが、ここに関数ヘッダコメントを表示することができます。

関数ヘッダコメントの書き方

別の記事 『Notes - Excel 連携：#25）罫線の設定 ①』で作成した RGB という関数を例に記載します（関数の中身は今回の記事とは何ら関係ありません）。

コメントを記載する前の状態は次の通りです。

Public Function RGB(_               ByVal vbyR As Byte, ByVal vbyG As Byte, ByVal vbyB As Byte) As Long     RGB = vbyR + CLng(vbyG) * 256 + CLng(vbyB) * 256 ^ 2 End Function

この関数を使用したエージェントでは、以下のようにポップアップヘルプが表示されます。

スクリプトライブラリを開き、この関数にヘッダコメントを記載します。

%REM RGB メソッド　( lsXls ライブラリ ) --------------------------------------------------- R, G, B の各要素から Excel で使用する色番号を返します。 　 ◆ 引数 vbyR　 Byte 赤 vbyG　 Byte 緑 vbyB　 Byte 青 　　 ◆ 戻り値 Long %END REM Public Function RGB(_               ByVal vbyR As Byte, ByVal vbyG As Byte, ByVal vbyB As Byte) As Long     RGB = vbyR + CLng(vbyG) * 256 + CLng(vbyB) * 256 ^ 2 End Function

このように記述すると、この関数のポップアップヘルプに関数ヘッダコメントが表示されます。

変数コメントの場合

変数コメントは、定義の右側にコメントを記述することとしていました。ただ、このコメントはポップアップヘルプに表示されません（事例は変数ではなく定数）。

ポップアップヘルプの機能は、定義直上のコメントしか表示しない仕様のようで、以下のように記述すると表示されました。

ドミノデザイナーでは、右クリックメニューから [宣言を開く] を選択すると、関数や変数などの定義を参照でき、この機能を使えばコメントも確認できます。ただ、元の位置に戻る機能がないので、コメント参照のためだけに画面を切り替えるのは、作業効率が悪くなります。

関数内の変数であれば、宣言と変数の利用は近接するので参照も容易ですし、元の位置に戻るのも簡単です。このような側面から、コメントは宣言の右側とし、プログラムの行数を減らし、関数の一覧性を優先しました。蛇足ですが、関数内の変数のコメントを頻繁に参照する必要がある関数は仕様が複雑すぎるのかもしれません。独立性の観点から改善を検討すべきかもしれませんね。

先の事例のように定数宣言や Private 変数の場合や Public 変数（独立性の観点から積極的にお勧めはしませんが）では、ポップアップヘルプの活用は有効な記述方法だと思います。

まとめ

今回は、記述したコメントの有効活用を紹介しました。この方法を使えば、開発中の作業効率が上がるだけでなく、コメントの不備にも気づくことができます。コメントを記述する動機付けにもなりますので、コメントが更新されていないという状況は減るかと思います。

私の開発チームでは、スクリプトライブラリ開発において Public な関数や定数には今回のようにコメント記述するルールにしています。