「数千行のソースのコメントアウトをとったら数百行だった」というコメントを頂いたのですが、コメント記述標準を定義する人は目的と手段をキチンと認識して欲しいものです。
VS2005からまともにXMLコメント機構が働くので
''' <summary>
''' iとg で計算する
''' </summary>
''' <param name="i"></param>
''' <param name="g"></param>
''' <returns>計算結果</returns>
''' <remarks></remarks>
Public Function 計算(ByVal i As Integer, Byref g As Double) As Double
::::
End Function
呼ぶ側
dim i as Integer=34
dim g as Doulbe =55.3
dim ans as Doulbe = 計算(i,g) ' gは byrefなので注意
先ずFunction部を書いてその後に'''を加えれば、 param句が自動生成してくれます。これは便利ですね。
VBの言語仕様のため、 呼ぶ側の 計算(i,g) だけ見ても、byRefかbyValか区別ができません。(VBに対する不満ですが)
それで 例のようなコメントを書いて、混乱しないようにしてます。
「コメントは処理内容を記述せよ」という意味を曲解している開発者を時々(いつも?しばしば?)見かけます。
a = (b + c) /2 ' bにcを加えて2で割る
こんなコメントは無いほうがマシ。 意味は bとcの算術平均を求めているのだから, '
a = (b + c) / 2 'aはb,cの算術平均
と書くべきです。
演算の業務的な意味をコメントにすれば、言語を知らない(読めない)人でもこの辺でこの処理をしていると判断が付きます。
最初に示した XMLコメントも便利ですが、個人的には好まないです。この例でいうと、function 計算(i,,,)の引数と戻り型はステートメンと見れは判ることなので、
わざわざ7行を費やしてコメントを書くのがイヤ。IDEなどのソースエディタで7行も非実行文があると、ソースを追いかけるのに改ページやスクロールを頻繁に行うことになり気が散るのです。
これは個人的な感覚ですので是非は問わないで下さいね。
ここで出てくる <Remarks>句の中に計算() の仕様を書いているソースを見かけます。
そのおかげで、1ページ40行見える Editorで在っても, 33行がコメントで実際の処理は 7行だったりします。
業務アプリであるならば、プログラム作成時には仕様書がある筈ですし、ロジックが変わったら仕様書も更新されるはずです。
仕様書があるので <Remarks>仕様書.xxPageの規則xxxの計算</Remarks>で良いと思うのです。
このように書くと「仕様変更なり仕様バグが頻繁に起こり仕様書に反映させる暇がない。実働しているソースが全てだ。」という人もいます。
そうでしょうか。そういう人は得てして。Function()本体は修正しても <remarks>のコメントは修正していない事が往々にしてあります。
「自分のソース内のコメントの維持も出来ないのに正当化するな」と思ってしまいます。
読みやすいコメントや後日の自分に伝えるコメントって本当に難しい。