仕事でソースコードを書いている人に質問です。　現場で書かれているソースコードの中のコメントの書き方を教えてください。

◆追加するとき

//add 20089/02/11 start

コード

//add 20089/02/11 end

◆削除するとき

//del 20089/02/11 start

//コード

//del 20089/02/11 end

◆更新するとき

//update 20089/02/11 start

//修正前のコード

修正後のコード

//del 20089/02/11 end

・英語コメントは書く方も読む方も脳内翻訳の無駄なので日本語で分かりやすく簡潔に書きます。

・修正点に関するコメントはソースコードには直接書くことはあまりせず、Subversion等のソース管理システムへのコミットログとして残します。

○ソースコードの中のコメントの書き方

プログラムファイルヘッダとコーディング内に分けて書きます。

１）プログラムヘッダ

/**********************************************

//

//　プログラム名： ○○処理

//

//　概要：画面から入力した西暦日付を和暦へ変換する

//

// Designed On 2009.02.11 By Bigvan

// Update On 2009.02.11 By bigvan Ver2.1.1 画面入力に日付チェックを追加

//

/**********************************************

２）コーディング内

//aが空文字の場合はNothingをセットする

if(a="") then

a="Nothing"

end

○修正ポイントの管理

下記のようにしています。

後でどのような変更をしたか？なぜ変更したかが「画面入力に日付○ソースコードの中のコメントの書き方

プログラムファイルヘッダとコーディング内に分けて書きます。

１）プログラムヘッダ

/**********************************************

//

//　プログラム名： ○○処理

//

//　概要：画面から入力した西暦日付を和暦へ変換する

//

// Designed On 2009.02.11 By Bigvan

// Update On 2009.02.11 By bigvan Ver2.1.1 画面入力に日付チェックを追加

//

/**********************************************

２）コーディング内

//aが空文字の場合はNothingをセットする

if(a="") then

a="Nothing"

end

○修正ポイントの管理

下記のように管理しています。

後でどのような変更をしたか？なぜ変更したかが「画面入力に日付チェックを追加」を検索することによってすぐに解かります。

１）プログラムヘッダに変更点を記述します。

// 2009.02.11 Update By bigvan Ver2.1.1 画面入力に日付を追加

２）コーディング内下記のように記述します。

・追加

// ADD START 画面入力に日付チェックを追加　

追加内容1

追加内容2

追加内容3

//ADD END 画面入力に日付チェックを追加

・変更

// UPD START 画面入力に日付チェックを追加　

//変更前1

//変更前2

変更後1

変更後2

変更後3

//UPD END 画面入力に日付チェックを追加

・削除

// DEL START 画面入力に日付チェックを追加　

//削除内容1

//削除内容2

//削除内容3

//DEL END 画面入力に日付チェックを追加」を検索することによってすぐに解かります。

１）プログラムヘッダに変更点を記述します。

// 2009.02.11 Update By bigvan Ver2.1.1 画面入力に日付を追加

２）コーディング内下記のように記述します。

・追加

// ADD START 画面入力に日付チェックを追加　

追加内容1

追加内容2

追加内容3

//ADD END 画面入力に日付チェックを追加

・変更

// UPD START 画面入力に日付チェックを追加　

//変更前1

//変更前2

変更後1

変更後2

変更後3

//UPD END 画面入力に日付チェックを追加

・削除

// DEL START 画面入力に日付チェックを追加　

//削除内容1

//削除内容2

//削除内容3

//DEL END 画面入力に日付チェックを追加

修正ポイントの管理はコメントではなく、ソース管理システムで行います。

コード上にコメントで記載すると、コードがどんどんと汚くなって見にくくなっていきます。

それ以外のコメントは、

ファイルの先頭にそのファイルで記述するコードの説明、

関数、クラス毎の説明です。

///////////////////////////////////////////////////

// 内容:ファイルの説明

// 作成:日付 名前

// 修正:日付 名前 修正内容

///////////////////////////////////////////////////

処理に関する説明は極力書かない。コメントがなくても分かるようにコーディングする。

とはいえ、現実にはコードが分かりにくくなってしまうので、

複雑な処理では処理手順などを記述します。

// リストを並び替える

// 1.xxxを検索する

// 2.検索したxxxを・・・する

// 3.・・・・・する

コードをみれば分かるようなコメントは書きません。

// aaaとbbbが等しいときはreturn

if(aaa == bbb) return;

重要だと考えている2点を。

• 処理の内容ではなく、意図を書く

//rにnum/2を代入
r = num / 2;
//abs(r - num/r) が TOLERANCE 以下になるまで繰り返し
while( abs(r - num/r) > TOLERANCE)
{
   r = 0.5 * (r + num/r);
}
printf("r = %lf", r);

ではなくて、下のようなコメントにします。

//ニュートンラプソン法を使って、numの平方根を計算する
r = num / 2;
while( abs(r - num/r) > TOLERANCE)
{
   r = 0.5 * (r + num/r);
}
printf("r = %lf", r);

• 修正前後の履歴確認は、ソース管理システムにお任せ

また、[amazon:Code Complete第2版〈下〉]の、32章：読めばわかるコードに、

「効果的なコメントのポイント」という内容があり、参考になると思います。

（上の内容も含めて、詳しく書いてあります。）

組込み屋でc言語用ですが、こんな感じです。

/***********************************************************************

[機能]SIO送信

[関数名]void send_sio(unsigned char *s,int len)

[入力]s:送信文字列

len:送信文字列長

[出力]なし

[備考]

***********************************************************************/

void send_sio(unsigned char *s,int len)

{

}

Excelで書いた関数仕様書から上記コメント付きスケルトンソースを作成したり、

上記のコメントの入ったソースから関数仕様書を生成するマクロを使っていました。

↓

https://sourceforge.jp/projects/testools/downloads/37618/spec.xl...

前回の回答に入力ミスがあり、大変醜くなっていました。

下記の通り修正します。

○ソースコードの中のコメントの書き方

プログラムファイルヘッダとコーディング内に分けて書きます。

１）プログラムヘッダ

/**********************************************

//

//　プログラム名： ○○処理

//

//　概要：○○○

//

// Designed On 2009.02.11 By Bigvan

// Update On 2009.02.11 By bigvan Ver2.1.1 処理名

//

/**********************************************

２）コーディング内

//コーディングコメント

コーディング

○修正ポイントの管理

１）プログラムヘッダに変更点を記述します。

// 2009.02.11 Update By bigvan Ver2.1.1 処理名

２）コーディング内下記のように記述します。

・追加の場合

// ADD START 処理名　

追加内容

//ADD END 処理名

・変更の場合

// UPD START処理名　

//変更前

変更後

//UPD END 処理名

・削除の場合

// DEL START 処理名　

//削除内容

//DEL END 処理名

ここ数年はdoxygenのフォーマットで書くことが多いです。

http://www.doxygen.jp/

自動生成されたドキュメントもそれなりに使えますので。