増子良太のブログです

増子良太が書いているブログです。テーマをしぼらず、思いついたものをただひたすら書いていきます。

やっぱりソース内のコメントは大事なんだぞと声を大にして言いたい

      2014/01/07

最近新入社員の方が入るということで、ありがたい事に教育係をやらせてもらえることになりました。

今まで人を育てた!って経験もなくて、社歴だけ長くなってきて、オレってこんなんで良いのかな。。。なんて思っていたところに。

最初は面倒だとしか思っていなかったけど、色々なことを教えるうちにまだまだ自分の知識も固まってなかったり、一部しか知らない事が多くて、ダメダメですねと思う事も多い今日この頃です。

そんな中、今日思ったのは、『ソース内のコメントは大事!!』てっことです。

色々なことを教えつつ、今までの経験からこの辺のソースが役に立つから読んでみてくださいね、なんて教えてみたものの、、、

最初に来た質問が

これって何をしているんですか!?

でした。

いや、そんなもんコメント読んでソース見れば大体わかると思うけどーと言いながらソースを見てみると、、、コメントが一切ありませんでした。

コーディングルールなんて厳密なものではないのですが、メソッドのコメントはこういう風に書こうとチームで決めていたルールなどもありましたが、毎回毎回リリースがギリギリになってしまうため、コメントを書いている暇がなかったのです。

改めて探してみると、自分で書いたソースの中にもコメントがないものが多くありました。

これはまずい。

正直、ドキュメントなんて書いても読みません、と僕個人的には思っています。

プログラマなら、ソースを読んだ方が早い時の方が多いです。→これはおそらく小中規模のプロジェクトでしか通用しないとは思いますが。

ただ、何もコメントが書かれていないソースを読まされるほど大変なときはありません。メソッド名や変数名などからなんとなくこんな感じかなと想像してみるものの、やはりコメントにこんなことをしているメソッドですと書かれると、それを前提に読むので、読んだ時に理解するまでのスピードが違います。

僕はPerlを覚えたのも社内にあるプロジェクトの保守をやらざるを得ない状況になり、ドキュメントもなかったのでソースを読んで読んで読みまくりました。

他人のソースを読んで理解するまでの早さには自信があるくらいです。

しかし、やはりコメントがあればもっと楽に読めるのになぁと思った事はたくさんあります。

メソッド一つにしても、引数が何個あって、どういった形式で呼び出したら良いのか、コメントがあれば一瞬です。

コメントがなければ、ソースの中に書いてある事を有る程度読み込んでから、この引数の型はこれか、なんてことを導きだす必要があります。正直面倒です。ただ呼び出したいだけなのに。

自分で書いている時にはコメントなんて、余裕があれば書けば良いと思っていますが、書いた時には覚えていても、書いた後何ヶ月後かに見た時にはすっかり全てを忘れてしまっていて、もう一度書いた時のことを思い出しながらソースを追いかけるということをしなければなりません。

他人が書いたソースなら、その作業がもっと辛いんです。このメソッドは特殊で、こんな事情があって使われていないんだよってメソッドもコメントがなければ呼び出せちゃうわけで、そこで気づかないエラーをいつかの日にクレームとして対応しなければならなかったり。

コメントがあれば全てが解決するわけではありませんが、ソースを読むための助けには絶対になります。

この記事は自分自身への戒めと、世の中のソースがちゃんとコメントが書かれたソースになっていくことを願いながら書いてみました。

皆さん、ソースにはちゃんとコメント書きましょうね!コメントの質はどうあれ。。。

 - その他