生産性を上げるにはプログラマの高水準知識を意識する 問い合わせ

プログラムにおけるコメントの意義とは？

プログラミングには「コメント」という機能があります。コードを読む人間が後で分かりやすいように残しておくメモ書きのようなものです。コンピュータが直接認識するものではないので、あっても無くてもプログラムの動作には全く影響しません。しかし、「優れたコードには多くのコメントがある」という格言があるように、コメントを書くことは重要視されていて奨励されています。
その一方で、「コメントが多すぎると見苦しいコードになってしまう」という問題点があるのも事実。プログラマにとって作成したプログラムは納品ドキュメントであり、相手に分かりやすいようにコメントを残すことは極めて重要です。どうすればプログラミングにおけるコメントの有効性を高めることができるのか、検討してみましょう。

コメントは高水準知識を意識して記述せよ

たとえばfoobarというclassを記述する際、public function __construct()というコードの近くに「foobar class のコンストラクタです」というコメントを書くのは無意味です。一目で分かる内容についてコメントで言及するのは完全な重複であり、時間的にも容量的にも無駄以外の何物でもありません。
ここで重要なのは、コードに書かれていない内容、すなわち「高水準知識」のみをコメントで書くことです。コードを見れば明らかな内容、「低水準知識」をグダグダと書く連ねるのは、プログラミングの原則であるDRY（Don’t repeat yourself）に反します。コードを見ただけでは分かりにくい重要なポイントをコメントで補完するようにしましょう。

ポイント1：メソッドの分割を意識してコメントを書く

コメントを書く際は、メソッドの分割が大切です。3～5行を1ブロックと見立てて、ブロックごとにコメントを書くプログラマがいますが、これではメソッドが1スクリーン内に収まらなくなります。1メソッドに1コメントのペースで十分でしょう。後で見返す時のことを考慮して、メソッドが1スクリーン内に収まるように分割を工夫すべきです。

ポイント2：クラスや変数の名前を活用してコメントを短縮する

コードを記述する際には、メソッドやクラス、変数に名前を割り当てていくことができます。普段なんとなく適当な名前を付けている方は、これらの名前を工夫してみてはいかがでしょうか。最適な名前を割り当てれば、その名前を見ただけでロジックの意図を読み取ることができます。それは同時に無駄なコメントの節約にもなります。
優れたプログラマは、他の人が見落としがちな些細な機能も有効活用してコードを記述しています。闇雲にコメントを書き連ねるのではなく、名前を変更することで必要な情報を読み手に伝えるテクニックを磨くのも一つの手です。