2014年8月2日土曜日

ソースコードのコメントは「省力化」のために入れる

プログラミングにおけるソースコードに書くコメントについて、他のエンジニアと話す機会が最近あって、その方は「コメントは最後の手段」と言っていました。

要するにその方によれば、例えば関数やメソッドの名前・引数の名前などでコード自体が機能を説明するようにすべきであり、コメントに説明を書くのは最後の手段であると。

確かに、コード自体が機能を説明していることは重要です。関数やメソッドの名前・引数の名前は読めば何を意図しているのか分かるようにすべきであり、そのためなら多少名前が長くなっても構わないと思います。一つの関数やメソッドが長くなり過ぎたり条件分岐や繰り返しといった制御構造のネストが深くなり過ぎないように、適切に分割していくべきです。

それは確かなのです。しかし、どうしても「ソースコード自体が機能を説明する」ことには限度があります。その目的や意図や、動作の詳細を説明しきれない場合は結構多いのです。

もう1つ、ソースコード自体を細かい関数やメソッドに分割した場合、もし意図がわからなければ、結局次々と呼び出し元の関数やメソッドを追っていかなければいけません。これも実際に結構な労力です。

本当に何をしているか理解するには、やはり最後はソースコードを追っかけるしか無くて、関数やメソッドの名前・引数の名前だけで何をしているか説明できるというのは無理があると思っています。それは自分自身が書いたソースコードならばともかく、他人の書いたソースコードになれば、もはや不可能です。

ソースコードを追っかける際に一番難しいのは、やはりどういう意図と目的を持って書かれているかということで、そこはコメントに書いてあるのとないのとでは理解のスピードに雲泥の差が生じます。

Web上にあるプログラミング言語のリファレンスマニュアルを思い出してみると、関数やメソッドの引数の想定する型や説明、及び返り値のとりうる型や説明、そして関数が行う処理の説明が意図と目的が分かるように書いてあります。だから、例えばRubyやPHPの関数やメソッドを、その元となるC言語のソースコードを全く知らなくても使えます。ちょっと強引な例ですが、十分に詳細な説明があれば、その先のソースコードは追っかけなくてもよくすることができる、ということです。

もちろん、プログラミング言語のリファレンスマニュアル並みの詳細度を全てのプログラミングのソースコードのコメントに求めていたら、ソースコードを書く側が余りにも大変になってしまいますが、コメントがきちんと書いてあることによって、ソースコードの理解は格段に速く楽になることは間違いありません。結局ソースコードを追っかけることになったにしても理解度とスピードが全然違うでしょう。

書いたら捨てる使い捨てのコードならばともかく、後々のメンテナンスを自分や他人が行うことになるコードなのであれば、コメントを上手く入れることが非常に重要であり、特にライブラリ的に多数の箇所から参照される関数やメソッドの先頭には、引数の想定する型や説明、及び返り値のとりうる型や説明、そして処理の意図と目的が分かるようにコメント入れるべきである、というのが僕の意見です。それは後々の「省力化」になるのです。

※この記事について指摘・意見・提案・感想などありましたら下のコメント欄にどうぞ。

0 件のコメント:

コメントを投稿