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

またコメントの例も書いてください。

また修正ポイントの管理などはどのようにしているかお教えください。

回答の条件
  • 1人2回まで
  • 登録:2009/02/11 10:06:33
  • 終了:2009/02/18 10:10:03

回答(8件)

id:hijk05 No.1

hijk05回答回数1307ベストアンサー獲得回数232009/02/11 11:08:53

ポイント17pt

◆追加するとき

//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

id:php-beginner

ありがとうございます。

シンプルでわかりやすいですね。

2009/02/11 13:06:09
id:y-kawaz No.2

y-kawaz回答回数1421ベストアンサー獲得回数2262009/02/11 16:28:55

ポイント17pt

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

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

id:php-beginner

ありがとうございます。

コメントの例を書いて頂けると助かります。

2009/02/11 20:10:23
id:bigvan No.3

bigvan回答回数12ベストアンサー獲得回数12009/02/11 16:56:48

ポイント16pt

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

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

1)プログラムヘッダ

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

//

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

//

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

//

// Designed On 2009.02.11 By Bigvan

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

//

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

2)コーディング内

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

if(a="") then

a="Nothing"

end

○修正ポイントの管理

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

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

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

1)プログラムヘッダ

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

//

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

//

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

//

// Designed On 2009.02.11 By Bigvan

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

//

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

2)コーディング内

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

if(a="") then

a="Nothing"

end

○修正ポイントの管理

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

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

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

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

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

・追加

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

追加内容1

追加内容2

追加内容3

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

・変更

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

//変更前1

//変更前2

変更後1

変更後2

変更後3

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

・削除

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

//削除内容1

//削除内容2

//削除内容3

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

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

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

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

・追加

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

追加内容1

追加内容2

追加内容3

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

・変更

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

//変更前1

//変更前2

変更後1

変更後2

変更後3

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

・削除

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

//削除内容1

//削除内容2

//削除内容3

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

id:rome0315 No.4

rome0315回答回数13ベストアンサー獲得回数32009/02/12 23:14:32

ポイント16pt

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

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



それ以外のコメントは、

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

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

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

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

// 作成:日付 名前

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

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


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

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

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


// リストを並び替える

// 1.xxxを検索する

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

// 3.・・・・・する


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

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

if(aaa == bbb) return;

id:php-beginner

ありがとうございます。

修正はソース管理で複雑な処理に限ってはコメントを残すという事ですね。

2009/02/15 09:27:10
id:okamog No.5

okamog回答回数3ベストアンサー獲得回数02009/02/13 01:44:49

ポイント16pt

重要だと考えている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章:読めばわかるコードに、

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

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

id:php-beginner

ありがとうございます。

意図を書くという意識をもってコメントを書きたいと思います。

2009/02/15 09:31:34
id:garyo No.6

garyo回答回数1782ベストアンサー獲得回数962009/02/13 23:48:56

ポイント16pt

組込み屋で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...

id:php-beginner

ありがとうございます。

こういったマクロがあるんですね。

2009/02/15 09:24:12
id:bigvan No.7

bigvan回答回数12ベストアンサー獲得回数12009/02/14 02:23:07

ポイント16pt

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

下記の通り修正します。

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

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

1)プログラムヘッダ

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

//

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

//

// 概要:○○○

//

// Designed On 2009.02.11 By Bigvan

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

//

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

2)コーディング内

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

コーディング

○修正ポイントの管理

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

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

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

・追加の場合

// ADD START 処理名 

追加内容

//ADD END 処理名

・変更の場合

// UPD START処理名 

//変更前

変更後

//UPD END 処理名

・削除の場合

// DEL START 処理名 

//削除内容

//DEL END 処理名

id:php-beginner

ありがとうございます。

ヘッダで履歴を追えるわけですね。

2009/02/15 09:13:17
id:ydf No.8

ydf回答回数11ベストアンサー獲得回数02009/02/17 20:45:55

ポイント16pt

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

http://www.doxygen.jp/

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

  • id:standard_one
    ウチは実働部隊のトップとマネージャーがコメントも設計書も不要とかおぬかしになるおバカチャンなので、個人でこっそり設計管理ツール作ってます。

この質問への反応(ブックマークコメント)

トラックバック

「あの人に答えてほしい」「この質問はあの人が答えられそう」というときに、回答リクエストを送ってみてましょう。

これ以上回答リクエストを送信することはできません。制限について

絞り込み :
はてなココの「ともだち」を表示します。
回答リクエストを送信したユーザーはいません