不必要なコメント・必要なコメント(1/2)
コード内のコメントについてはプログラミングにおいて最も議論されやすい話題ですね。人によって意見が食い違う部分も多いですが、適切なコメントを付けられるかどうかで開発効率は圧倒的に変わるのは間違いありません。
今回の記事ではまず「不必要なコメント」について取り上げたいと思います。 不必要であるがゆえに開発途中に見かける例も少ないので、あくまでも初心者・中級者向けです。
不必要なコメント一覧
コードの処理をそのまま翻訳したコメント
if文の手前に書いてある「if文による条件分岐」系のコメント。見ればすぐに分かります。 新入社員の子がこういう類のコメントを書いていたのを見ましたが、プログラミング初心者は不安になって書きがちです。でも自分でそう書いたということは理解しているから書けるのであり、結局誰の助けにもなっていません。消しましょう。 自分も昔だったら「コメントがあって丁寧なコードだなあ」と思っていた気がします。入門用の本には説明として書かれていることがあるので、それを無意識に模範としてしまうのかもしれないですね。
バグがあるのでこの関数は使わないで系コメント
これも新入社員の子が書いていました。全員が全員そのファイルを見ているわけではないです。 アサート処理を入れておくとか関数自体をコメントアウトして使えなくしてしまうとかの方が安全です。
すぐにコードが改善できるコメント
funcAの横にある「〇〇を計算する関数」系のコメント。コメントで説明をするのではなく、funcAという関数名を変えて実行されるコードそのもので説明すべきです。 ただし時間がなくて急遽手当てした場合など、リファクタリングにまで手が回らないケースもあります。そういう時は後でこっそり修正しましょう。
長すぎる説明コメント
あまりに説明が長くなりそうな場合はテキストファイルなどに書き、そちらを参照するようにコメントしておきましょう。分かっている人にとってはそもそも読まなくていいですし。 また長すぎる説明が必要になること自体も疑った方がいいです。別のロジックでよりシンプルなコードにできるかもしれません。
難しすぎる説明コメント
このコメントはいったいどう意味なんだ...と何ヶ月経っても分からないコメントがあります。そんなに悩むということはそのコメントが役割を果たしていないことになります。 そんなことで頭を抱えるくらいなら、思い切って消してしまってもいいかもしれません（断定はしない）。あと頑張って英語でコメントを残そうという習慣があったりなかったりしますが、英語で書いた故に何が言いたいのか分からなくなってしまっては本末転倒です。
過去の実行コードを取っておくコメント
理解しきれていないので消すのが怖い、仕様が定まり切っていないのですぐに変更が効くように、など理由は様々です。 開発途中であれば残しておいてなんら問題はないのですが、開発が終わった後もこの類のコメントが残っていることがあります。 これが積み重なると、どんどんと見にくいコードになっていってしまいます。 理解しきれずに不安なまま変更を加える必要がある場合は非常にバグを仕込みやすいので、できる限り理解することが先決です。 初心者でなくてもやりがちなNo.1の例だと思います。
履歴コメント
「〇月〇日にこういう変更を加えました」系のコメント。これは初心者どうこうではなくコーディングルールの問題ですね。昔は必要だったのかもしれないですが、今はファイル管理システムを使うのが当たり前なのでそのコミットログを見ればよいだけです。そもそもコミットログの方が差分も見れて信頼できます。 ファイル管理システムを使っていない場合はそれ自体が問題と認識すべきです。エクセルファイルのように簡単に差分が見れないファイルだったらありかも。
コメントが不必要な理由一覧
コメントの種類ではなく理由という切り口でも分類してみましょう。内容は上と被ります。
コードの量は少ない方が分かりやすいから
1000行のコードを読み解くより、100行のコードを読み解く方が簡単です。 すなわちもしコメントが理解の助けに全くなっていない場合はない方が行数が減ってマシです。
コメントそのものにもコストがかかるから
「コメントに目を奪われる時間」「コメントを理解する時間」「コメントの信頼性を確かめる時間」など、意外とコメントそのものにコストがかかってしまうものです。
嘘である可能性があるから
コメントが書かれた後に実行コードの修正が入るとコメントの内容が嘘になってしまいます。後々のバグに繋がります。 コメントは実行コードではないとは言え、”実行コード予備軍”くらいの影響力はあります。
メンテナンスが必要だから
コメントも随時修正必要だなあ....面倒だなあ、と思う場面は多いです。たまにしか見ないファイルなら許せますが、頻繁に手を加えるファイルなら本当にそのコメントは必要か？と吟味しましょう。
リファクタリングが可能だから
分かりやすいコード＞分かりにくいコード＋コメントによる説明 とよく言われます。
まとめ
コメントを書くよりコメント消す方が簡単に思えますが、「不適切なコメントだ」と判断するのは意外と難しいです。なので、そう判断できたのなら後々他の方が同じ苦労をしないように消してしまうのが吉です。 要らないコメントを消してコードをスッキリさせたら、今度は適切なコメントを加えていくフェーズです。
次回は必要なコメントについて記事を書く予定です。
