人力検索はてな
モバイル版を表示しています。PC版はこちら
i-mobile

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

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

●質問者: php-beginner
●カテゴリ:コンピュータ ウェブ制作
✍キーワード:いるか コメント ソースコード ポイント 現場
○ 状態 :終了
└ 回答数 : 8/8件

▽最新の回答へ

1 ● hijk05
●17ポイント

◆追加するとき

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

◎質問者からの返答

ありがとうございます。

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


2 ● y-kawaz
●17ポイント

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

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

◎質問者からの返答

ありがとうございます。

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


3 ● bigvan
●16ポイント

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

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

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 画面入力に日付チェックを追加


4 ● rome0315
●16ポイント

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

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



それ以外のコメントは、

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

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

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

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

// 作成:日付 名前

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

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


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

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

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


// リストを並び替える

// 1.xxxを検索する

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

// 3.・・・・・する


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

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

if(aaa == bbb) return;

◎質問者からの返答

ありがとうございます。

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


5 ● okamog
●16ポイント

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

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

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

◎質問者からの返答

ありがとうございます。

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


1-5件表示/8件
4.前の5件|次5件6.
関連質問


●質問をもっと探す●



0.人力検索はてなトップ
8.このページを友達に紹介
9.このページの先頭へ
対応機種一覧
お問い合わせ
ヘルプ/お知らせ
ログイン
無料ユーザー登録
はてなトップ