プログラムを行う際のコメントやコメントアウトの流儀はどのように行うのがスマートでしょうか？

リンク先を読んでみてはどうでしょう。

ちなみに、個人的には、変数を除いて、関数単位以上のコメント(1行毎など)は、あまり不要かと思います。

と言いますか、1行毎にコメントを書かなければ分からないようなコードは書くべきではないと思います。

日付・コメントアウト等は、VCS 等を使うことで、ヘッダ以外への記述は、ほぼ不要と思われます。(つまりコメントも多ければいいというものではないと思います。)

コメントの流儀（書き方）は、開発を行っている会社やプロジェクト毎に

異なったりすると思います。

個人的には、ドキュメント生成ソフトの流儀にあわせてコメントを

つけるのが良いのでは？と思います。

幸い、VB.NET（VC#）では、ドキュメント（HTML ヘルプなど）を

自動生成するツール（NDoc など）があります。

VB.NET で、NDoc を利用するには「VBCommenter Help」という

アドオンを導入する必要がありますが、これを使用することによって、

ドキュメント生成用のタグなどが自動挿入され、コメントを入力しやすくなります。

＜VB.NET でドキュメント（HTML ヘルプなど）を自動生成する流れ＞

1. 「VBCommenter Help」をダウンロード/インストールします。

■ VBCommenter Help Documentation

http://www.gotdotnet.com/team/ide/helpfiles/VBCommenter.aspx

■ VBCommenter PowerToy Development: Releases: Home（ダウンロード）

http://www.gotdotnet.com/workspaces/releases/viewuploads.aspx?id...

2. 「NDoc」をダウンロード/インストールします。

■ NDoc Online -日本語版-

http://ndoc-jp.sourceforge.jp/

3. VB.NET で、コメントを入力します。

関数の宣言の前で「’’’」と書いて [Enter] キーを押下すると、

以下のようなコメントが自動挿入されます。

[VB.NET]

’’’ -----------------------------------------------------------------------------

’’’ <summary>

’’’ ’’’

’’’ </summary>

’’’ <param name=”val”></param>

’’’ <returns></returns>

’’’ <remarks>

’’’ </remarks>

’’’ <history>

’’’ [Administrator] 2004/XX/XX Created

’’’ </history>

’’’ -----------------------------------------------------------------------------

Public Function Plus(ByVal val As Integer) As Integer

End Function

4. プロジェクトをビルドします。

5. NDoc を起動します。

アセンブリ（*.exe/*.dll）を追加して、[Documentation] - [Build] を選択します。

これで、コメントを元にしたドキュメントが生成されます。

（ドキュメントの形式は「HTML ヘルプ形式」や「HTML 形式」など選択することが可能です。）

URL は、VBCommenter の使用方法（図入り）です。

URL に VB.NET のコーディング規約の例が載っています。

URL は、コーディング規約に関連する情報です。

また、コメントアウトですが、開発中（デバッグ中）に、一時的にコメントアウトすることはありますが、

ソースの改変履歴として、残しておくということは、あまりしないほうが良いと思います。

（ソースが長くなり、見通しが悪くなる為。）

そのような改変履歴の管理には、ソース管理ソフト（Visual SourceSafe など）

が適していると思います。

http://www.hatena.ne.jp/ダミー:detail]

コード管理ツールなどで履歴管理されている場合は、古いコードはバッサリ消します。

見易さのためにはこれが一番ですね。

諸事情で残さざるを得ない場合は、新しい部分との対応が取れるように工夫します。

例えば、10行くらいのブロックなら、

’修正履歴とリンクできる情報、説明

’書換え始まりのマーク

新しいコード

’’’古いコード

’書換え終わりマーク

のようにしますし、

数行連続するなら

’修正履歴とリンクできる情報、説明

新しいコード

’’’古いコード

新しいコード

’’’古いコード

新しいコード

’’’古いコード

ということもします。

ブロック内などに点在しているなら、

’修正履歴とリンクできる情報、説明

：

修正したコード ’ 修正の補足

：

修正したコード ’ 修正の補足

：

もありです。

だいたい、新しい方を上に置きますか。

リリースするソースには、履歴との対応が付かない修正はないようにします。

あまりにも大量になる場合は、ポインタを書いて、ソースの末尾に持っていきます。

修正者とか日時とか障害や仕様変更の管理番号の情報は履歴の方に置きます。

いつまでも古いものを引きずるのは良くないので、骨は折れますが適宜整理します。

修正時のコメントについては、修正した人間がなぜそのように修正したか、思考の

後追いができるようなものがあると後々助かります。

大雑把な流れを見る、実際のコードを見る場合に余計な情報が少ないようなコーディングスタイルです。

→ この場合は、ソースの左寄りのみを追います

なぜそういうコーディングになっているのか？なぜコメントアウトされたのかなどの詳しい説明を見たい場合はソースの右寄りを見ます。

①コメント位置

　変数／定数宣言、初期化、主処理、終了処理などのブロック(文脈)が掴みやすいように

プログラム行と同じインデント(つまり対象行の上)に書きます。

　このとき　’##############　など区切りで挟んで強調します。

　ソースの説明、削除は、対象行の右側に全体のインデントを統一して書きます。

②日付

　修正、削除はやはり日付を入れますが、形式を必ず統一します。

　→ yyyymmdd or yyyy/mm/dd など

③ヘッダ

　ファイルヘッダ、関数ヘッダを必ずつけます。機能の説明、作成者、パラメータ説明など。

　修正履歴はファイルヘッダのみに書き、そのときに修正箇所が検索できるようなラベルを付けます。

　→ 例えば[20050531メモリリーク対策]など(ラベルに日付を入れる場合は②は不要ですね)