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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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