ソースコードの右側（同じ行）にコメントを書くべきではない理由

今回は、コーディングルールに関するお話です。

ソースコードにおけるコメントに関する部分というのは、その開発者の個性が最も反映される部分の一つです。また、開発チームの特性や空気感というのも、コメントを読めばある程度わかったりします。

そんな中で、ソースコードの右側（同じ行）にコメントを書くべきか否かという議論を目にする機会があったので、その点について少し考察してみたいと思います。

コメントを同じ行に書く

ソースコードの右側（同じ行）にコメントを書く、というのは具体的に以下のような状態です。

count = 0;  // カウンターを初期化します。
count++;  // インクリメントします。

他に、別の行にコメントを書く場合は以下のようになるかと思います。

// カウンターを初期化します。
count = 0;
// インクリメントします。
count++;

コーディングルールを規定する上で、コメントの記述方法に関してはどちらを採用すべきか、検討します。

コメントをソースコードと同じ行に書くメリットとしては、以下があると考えられます。

「簡単に気楽にわかりやすく書ける」というのが、同じ行にコメントが書かれやすい最もよくある理由だと考えられます。

コメントをソースコードと同じ行に書くデメリットとしては、以下があると考えられます。

同じ行に書くコメントは、良くも悪くも即席なところがあるので、うまく管理できない（表現できない）場合があるようです。

現場で実際に同じ行に書かれているコメントを見ると、気楽に書いているが故に、「そんなコメント必要ある？」と思わせるようなコメントが書かれていることもあります。

前提として、同じ行に書くコメントは1行1コメントとなるため、処理ブロック（複数行）に対する説明を記述できないので、コメントの粒度が高すぎる状態になってしまう傾向があるように思います。

こういったコメントに関する記述方法について検討する際に、毎回考えなければならないこととして、「コメントの粒度」をどうするかという問題があります。

個人的には、先ほど例に挙げたような粒度の高いコメント（処理毎の細かい動作の説明）は不要だと考えています。

// カウンターを初期化します。
count = 0;
// インクリメントします。
count++;

プログラミングの学習用の資料等ではこれくらい細かく説明されていた方が理解しやすいでしょうが、メンテナンスする上では、コメントが細かすぎると開発コストが増します。

それは、コメント量が多くなる分、コメントをメンテナンスするコストが増えるというのもありますし、何より読んだり書いたりする際に、全体のデータ量が増えるので可読性が損なわれるというのが大きいです。

このように「コメントの粒度」を考えてみると、不要なコメントというのが意外に多いです。

そしてやたらとコメントが多くなってしまうソースコードは、多くの場合、「関心の分離」がうまく出来ていない設計であることが多いです。

つまり、わかりやすくダメな例として、一つの関数の中身が100行を超えるような場合、当然ソースコードと同じ行（右側）に延々と動作を書いてわかりやすくしたくなるでしょう。100行の中のどの行で何をしているかをわかりやすくするために。

しかし、その関数内部の処理を適切に分離したとして、20個の関数の分離できたとしましょう。

そうすれば、1行毎の説明など不要で、20個の関数に関するDocコメント（JavadocやJSDoc、phpDocumentor等）さえあれば十分な状態に持っていけます。

私がこれまで関わってきたプロジェクトの中で、コメントだらけになって逆に可読性が低いプロジェクトというのは、どれもそういった設計の部分に難があるものばかりでした。

きちんと「関心の分離」を行い、関数やクラスの責任や役割を明確にし、「単一責任原則」を意識して設計すれば、Docコメントさえあればある程度は理解できるソースコードになるので、1行1コメントとなるようなコメントは不要になるだろう、というのが私の持論です。

まとめると、ステップ毎の細かいコメントは可読性を下げるので、1行1コメントとなってしまうような細かすぎるコメントの記述は避けた方がいいです。

きちんとした設計方針により、処理ブロック（関数やクラス）毎に責任を分担できれば、処理ブロック毎の大まかな動作をコメントとして記すことになるので、細かいコメントがなくても理解できるコードになります（JavadocやJSDoc、phpDocumentor等の活用）。

よって、そもそも1行1コメントという構造自体がそもそも相応しくなく、そういった設計になっていることが問題であるため、ソースコードの右側（同じ行）にコメントを書くようなかたちになっているプロジェクトは、まず設計を見直した方が良い、ということです。

そういう意味で、ソースコードの右側（同じ行）にコメントを書くべきではなく、そうなりそうならばそうならない記述を目指すべきだと考えます。