最初に
コードを編集している際にはコメントを適宜入力していると思います。「'」を入れれば以降はコメント扱いになりますね。
subやfunction (VBAだとプロシージャ)作成時にこのプロシージャは何をするものかについてコメントヘッダを記述することがあると思います。私は必ず書きます。見直したときにこのプロシージャって何だっけ?となる事を減らすことができます。
言うかて工藤
コメントヘッダに書くことって結構いっぱいありますね。プロシージャの名称(その説明)、引数(各個に説明)、戻り値の説明などなど。
また、ある程度修飾しておかないと、といったことから手作業で書くのは結構手間です。良くあるのはテンプレートを別途用意しておいて、それを張り付けてから記入する方法でしょうか。
アドオンを使ってコメントヘッダを生成
ここで、簡単にコメントヘッダの様式が生成できるアドオンを紹介します。
こちらで配布している
・AddLineNumbers VB6/VBA
・AddLineNumbers VBA for x64
がそうです。
32bit版と64bit版に分かれていますが、導入するOfficeのbit数に合わせてください。
導入方法は添付のreadmeをご覧ください。
導入後はすべてのOfficeで有効になります。(Access、ExcelどちらのVBEでも動きます)
使い方について。
例えば、次の様なプロシージャを書きました。
Private Function hogehoge(ByVal param1 As String, ByRef param2 As Integer) As Variant
その1行上で「'''」(アポストロフィーを3つ)入力すると
'''
Private Function hogehoge(ByVal param1 As String, ByRef param2 As Integer) As Variant
''' <summary>
'''
''' </summary>
''' <param name="param1"></param>
''' <param name="param2"></param>
''' <returns></returns>
''' <remarks></remarks>
Private Function hogehoge(ByVal param1 As String, ByRef param2 As Integer) As Variant
このようにコメントヘッダのレイアウトが生成されます。
後はそれぞれの項目に説明文を追記するだけです。
''' <summary>
''' ほげほげをいい感じにする
''' </summary>
''' <param name="param1">引数その1:文字列</param>
''' <param name="param2">引数その2:int</param>
''' <returns>できあがったほげほげ</returns>
''' <remarks>いい感じってなんですかね。</remarks>
Private Function hogehoge(ByVal param1 As String, ByRef param2 As Integer) As Variant
私は次のような感じでそれぞれを記載しています。
summary:プロシージャ名(簡単な説明)
param :引数の説明
returns:戻り値の説明
remarks:プロシージャの詳細説明や注意点
これで、コメントヘッダの完成です。
プロシージャを作ったときにコメントヘッダを残しておきましょう。
最後に
人は忘れる生き物です。先週の自分が何を考えてコードを書いたかなんて、今思い出せないことの方が多いです。そのため自分のためにコメントを残しましょう。
何を作ったか忘れてしまう前に。
余談
アポストロフィ3つでコメントヘッダが生成される動きは往年のvisualStudioっぽくて気に入っています。(現行のvisualStudioはどうなのかなぁ)