クラス化に挑戦： #14）クラス化とコメント

クラス化は開発効率を高めるために有効な開発手法となるのですが、コメントの書き方でさらに効果を高めることが可能です。

メソッドのコメント

一般的に通常の関数には関数の機能や使い方をヘッダコメントに記述します。クラスのメソッドも同様です。以下のコードは、前回 Location クラスに追加した CalcDistance メソッドにコメントを追加した例です。メソッドの使い方、引数の型と説明、戻り値、必要に応じて利用時の注意などを記載します。

%REM 自身の GPS 座標と引数で指定した座標との距離（m）を返します。 ◆ 引数 voDestination Location 距離を求める GPS 座標 ◆ データ型（戻り値）　 Double %END REM    Public Function CalcDistance(voDestination As Location) As Double       CalcDistance = distance(zdLatitude, zdLongitude, voDestination.Latitude, voDestination.Longitude)    End Function

このようにメソッドの直上に記述すると、デザイナーでメソッドを使用する際にポップアップヘルプとして表示されます。

クラスの利用者が欲するコメントを書いておくと、それだけで開発がすすめられます。ただのコード内のコメントではなくなりますので、記述するモチベーションが上がりますね。

プロパティのコメント

プロパティの定義は Get / Set の 2 つのモジュールに分かれます。コーディング上はそれぞれコメントを記述できますが、ポップアップヘルプに表示されるのは先に記述されたコメントとなります。ですので Get と Set のモジュールは連続して記述してその上にコメントを書くといいでしょう。

%REM 検索キーワードを表します。 ◆ データ型　 String ◆ アクセス　 取得、設定 %END REM    Public Property Get Keyword As String       Keyword = zsKeyword    End Property    Public Property Set Keyword As String       zsKeyword = Keyword    End Property

クラスのコメント

クラス定義の上に記述したコメントがポップアップヘルプとして利用されます。このヘルプはクラス定義に対してと New でそのクラスを選んだ場合とで共通です。

ですので、記述するコメントはクラスの機能とオブジェクトの作成方法である New の引数を記述しておきましょう。また、このクラスで必要となる他の他の設計要素についても記述すると間違いなく利用できますね。

%REM Location クラス　( lsGoogleMap ライブラリ ) --------------------------------------------------- GPS の位置情報を管理します 　 ◆ オブジェクトの作成　( New の引数 ) vdLatitude      Double   緯度 vdLongitude  Double   経度 ◆ 関連設計要素 　　（なし） %END REM Public Class Location          ・・・    Public Sub New(ByVal vdLatitude As Double, ByVal vdLongitude As Double)          ・・・    End Sub          ・・・ End Class

まとめ

今回はクラスライブラリのコメントと効果的な使い方についてまとめました。汎用的なクラスになればなるほど、自分以外の開発者が使うことになるので、それを意識してわかりやすく、使いやすいコメントを記述するようにしましょう。

前回

クラス化に挑戦