コードのコメント、何をどう書けばよいのか：9つのベストプラクティスを紹介

プログラマーがより良いコードを書くために役立つリソースは数多い。だが、より良いコメントを書くためのリソースはほとんどない。プログラム内のコメント量を測定することは簡単だが、コメントの品質を測定することは難しい。ではどうすればよいのか。

[＠IT]

　開発者向けQ＆Aサイト「Stack Overflow」は2021年12月23日（米国時間）、コードコメントを書くためのベストプラクティスを紹介した。これはミルズ大学のコンピュータサイエンスの教授であるエレン・スパータス氏による寄稿記事だ。

　この記事は2021年7月5日に掲載されたもので、同ブログで2021年に人気を博した記事のトップ10の1つとして再掲載された。

　スパータス氏は、「コメントは、出来の悪いコードの言い訳や修正として書くものではなく、（コードが表すものと）異なるタイプの情報を提供することで、良いコードを補完するものだ」との見解を示した。その理由としてシステムアーキテクトのピーター・ヴォーゲル氏が2013年に投稿したコメントに関する3つの事実を挙げた。

（1）コメントを書いて、維持するには費用がかかる
（2）コンパイラはコメントを無視するため、コメントの内容が正しいかどうか機械的に判断する方法はない
（3）コンピュータは（意図した内容とは異なっていても）コードに記述した通りに動作する

　そこでスパータス氏はコードコメントを書くためのベストプラクティスを9つのルールにまとめた。

　「プログラマーはこれらのルールに従うことで、自分とチームメイトの時間を節約し、フラストレーションを軽減できるだろう」と同氏は述べている。

ルール1　コメントの内容はコードが表すものと重複してはならない

　プログラミング初心者の多くは、コメントを書き過ぎる。入門コースの講師から、そうするように教育されたからだ。だが、コメントを書こうとする意識が強過ぎると、追加情報が全くない無意味なコメントを書いてしまいがちだ。典型的な悪い例を以下に2つ示す。