HOME > ソフテックだより > 第139号(2011年6月1日発行) 技術レポート「効果的なソースコードのコメントについて」

「ソフテックだより」では、ソフトウェア開発に関する情報や開発現場における社員の取り組みなどを定期的にお知らせしています。
さまざまなテーマを取り上げていますので、他のソフテックだよりも、ぜひご覧下さい。

ソフテックだより(発行日順)のページへ
ソフテックだより(技術分野別)のページへ
ソフテックだより(シーン別)のページへ


ソフテックだより 第139号(2011年6月1日発行)

技術レポート

「効果的なソースコードのコメントについて」

1. はじめに

コメントとは、プログラム言語で書かれたソースコードのうち、覚え書きとして記述される注釈のことです。
コメントは多ければ良いというものではなく、意味のないコメントはコーディング時間の無駄になるばかりか、ソースコードを読む人を混乱させることにもなります。
そこで本号では、効果的なソースコードのコメントの書き方や注意点について紹介したいと思います。プログラム言語はC言語で説明します。

2. コメントの分類

コメントを以下の5つに分類して説明します。

(1) ソースコードの繰り返し

ソースコードの繰り返しは、ソースコードに書かれている内容を自然言語で言い換えただけの内容です。そのため、コメント内容としてあまり意味がありません。
3.項の【例1】で具体例を紹介します。

(2) ソースコードの要約

ソースコードの要約は、数行のソースコードを1つの文にまとめたものです。数行のソースコード内容をまとめて確認できるため、ソースコードをすばやく読むことができます。
3.項の【例1】で具体例を紹介します。

(3) ソースコードの意図の説明

ソースコードの意図の説明は、ソースコード内容の目的を説明したものです。なぜそのようなソースコードにしたのかを記述することで、作成者の意図を理解することができます。
3.項の【例2】、【例3】で具体例を紹介します。

(4) ソースコードの説明

ソースコードの説明は、複雑なソースコード、注意が必要なソースコードを説明した内容です。
図1はシフト演算を使用して乗算、除算を行っていることをコメントで説明している例です。
なお、「(高速化のため)」部分のコメントは、『(3)ソースコードの意図の説明』の分類に該当します。

// 「ソースコードの説明」

// ((a × 8) ÷ 2) × 16をシフト演算(高速化のため)で計算
work = (( a << 3 ) >> 1) << 4;

図1. 「ソースコードの説明」例

(5) ソースコードの目印

ソースコードの目印は、あとで修正が必要なソースコードであることを示すために、作成者が目印として残しておくコメントです。
図2は「TBD」を目印とした例です。TBDは「To Be Determined:未解決」の略です。
修正したあとに目印を削除しますが、目印を削除し忘れることも考えられますので、担当者間で目印のスタイルを統一し、作業後に一括検索することで削除忘れを防ぐなどの対策が必要となります。

// 「ソースコードの目印」例

// TBD 未完成!リリース前に必ず修正すること!
return NULL;

図2. 「ソースコードの目印」例

3. 良いコメント例/悪いコメント例

いくつかのサンプルソースコードを元に、良いコメント例、悪いコメント例について説明します。

【例1】

図3の良い例では、3行のソースコードの要約を記述しており、一目で何をやっているソースコードなのか分かります。比べて、悪い例は1行1行のソースコード内容を言い換えただけのコメントとなっており、何を行っているのかはソースコード内容をよく確認しなければ分かりません。

/* 良い例(「ソースコードの要約コメント」) */

// 異常状態を交換する
temp = errState[0];
errState[0] = errState[1];
errState[1] = temp;
/* 悪い例(「ソースコードの繰り返しコメント」) */


temp = errState[0];        // tempにerrState[0]を代入
errState[0] = errState[1]; // errState[0]にerrState[1]を代入
errState[1] = temp;        // errState[1]にtempを代入

図3. 「ソースコードの要約コメント」と「ソースコードの繰り返しコメント」例

【例2】

図4のソースコードはソフテックだより 第109号 技術レポート「マイコン用ソフトウェアの高速化」の説明に使用したサンプルソースコードですが、10バイトのデータコピーを代入文でコピーしています。
コメントに「処理速度向上のため、代入でコピーする」とあるため、ソースコードの意図が分かりますが、もしコメントがなければ、「なぜfor文で記述していないのか?」と、ソースコードを読んだ人を混乱させることになります。

/* ソースコードの意図を説明したコメント例 */
unsigned char g_byBuf[10];

void FuncA(unsigned char *pbySrc)
{
    // 処理速度向上のため、代入でコピーする
    g_byBuf[0] = pbySrc[0];
    g_byBuf[1] = pbySrc[1];
    g_byBuf[2] = pbySrc[2];
    g_byBuf[3] = pbySrc[3];
    g_byBuf[4] = pbySrc[4];
    g_byBuf[5] = pbySrc[5];
    g_byBuf[6] = pbySrc[6];
    g_byBuf[7] = pbySrc[7];
    g_byBuf[8] = pbySrc[8];
    g_byBuf[9] = pbySrc[9];
}

図4. ソースコードの意図を説明したコメント例

【例3】

図5は条件文のコメント例ですが、良い例では理由に重点をおいたコメントになっていますが、悪い例では方法に重点をおいたコメントになっています。
コメントを記述するときは、より仕様レベルに近いコメントを記述したほうがソースコードの意図が伝わります。

/* 良い例(「理由に重点をおいたコメント」) */

// 新しいアカウントを作成する場合
if(accountFlag == 0)
{
(省略)
}
/* 悪い例(「方法に重点をおいたコメント」) */

// アカウントフラグが0の場合
if(accountFlag == 0)
{
(省略)
}

図5. 「理由に重点をおいたコメント」と「方法に重点をおいたコメント」例

【例4】

図6の悪い例は行末コメントを使用して記述しており、また行末コメントが複数行に適用されているため、どこまでのコメント内容なのかが分かりにくくなっています。
また、後述しますが、行末コメントは保守が難しく、使用するのはおすすめできません。

/* 良い例(段落コメント) */

// 割引率を計算する
for(rateIdx = 1; rateIdx < 10; rateIdx++)
{
(省略)
}
/* 悪い例(行末コメント) */


for(rateIdx = 1; rateIdx < 10; rateIdx++) // 割引率を計算する
{
(省略)
}

図6. コメント位置の例

4. 効果的なコメントのポイント・コメント記述時の注意点

効果的なコメントのポイントやコメント記述時の注意点について説明します。

(1) コメントは要約や意図を記述する

コメント例で説明した通り、要約や意図を記述することで、ソースコード内容の理解が格段に上がります。
また、関数ヘッダやファイルヘッダに概要を記述することで、ソースコードを読まなくても関数単位、ファイル単位で何をやっているのか理解することができます。
コメントは、次にソースコードを読んだ人がすぐに理解できることを意識して記述するのが良いです。

(2) 行末コメントは付けない

行末コメントは1行に対してのコメントであるため、意味のあるコメントを1行で書くことは難しくなります。
また、ソースコード部分を修正すると行末コメントの桁位置がずれるため、他の行末コメントと桁位置が合わなくなり、整列させるのに時間がかかり、余計な保守作業が増えます。
行末コメントはなるべく使用せず、数行を1ブロックとしたブロック単位でのコメント付けを行うのが良いです。
ただし、行末コメントが適しているケースもあり、データ宣言のコメントなどには行末コメントの方が向いています。

(3) ソースコードを見直すことも考慮する

プログラムにおいて、主役はコメントではなく、プログラム構造やデータ構造などです。
複雑なソースコードをコメントで補うよりは、修正が可能なのであればもっとスマートな手段を考えて、ソースコードを書き直したほうが良い場合があります。
ソースコードに対して適切なコメントが見つからない場合は、複雑なソースコードである可能性が高いです。

(4) ソースコードを修正するときはコメントも見直す

ソースコード作成者は意図的に嘘のコメントを書くことはありませんが、ソースコード修正を行った際に、修正ソースコードに対応したコメントを修正し忘れることがあり、それが嘘のコメントにつながります。
ソースコードを修正した際は必ず対応するコメントの修正が必要ないか、確認する必要があります。

5. おわりに

コメント部分はコンパイラには処理されないため、自由に記述することができます。しかし、書籍と同じで読み手を意識したコメントでなければ、全く意味のないコメントになってしまいます。
仮に自分1人だけが保守するソースコードであったとしても、数年経つとソースコード内容は忘れてしまうと思いますので、自分自身を守るためにも適切なコメントを残しておくことは大切です。

(M.A.)

[参考文献]
日経BPソフトプレス
『CODE COMPLETE第2版 下巻』

関連ページへのリンク

関連するソフテックだより

ページTOPへ