コメント不要論

世の中には、「ソースコード中にコメントは不要だよね」という つよつよ の方がいらっしゃるようです。

「コメントが不要」とする理由は「 変数名や関数名を見れば意味がすぐわかるからコメントなんていらないよね 」というものが多いように感じます。

それ、私はムリです。

コードで語れること、語れないこと

表現力があるか

私がムリだと感じるのは「伝えたいことを英語で表現しきれない」ためです。

英語が堪能ならマシになるのでしょうが、日常的に使用しない言語で扱える表現は底が知れている、というのがまずあります。

たとえば、

の「3章 誤解されやすい名前」に、 filter() という単語について記載があります。

filter() という言葉では、選択するのか、除外するのかがわかなく曖昧さが残る、というものです。

変数名が適切かどうかを議論することは実際良くありますけれども、パッとより適切な単語が出てくるか。

また、 自分だけではなく、チームメンバーにも理解してもらいやすいか

既存コードに右ならえして、 getHoge() みたいな関数名なりがちなら、適切な単語を選ぶために苦労しそうです。

どんどん長くなる

また、英語は 意味が増えるたびに横に長くなっていく という特徴があります。

日本語だと、漢字は難しくなっても、2, 3 語で表現できることってたくさんありますけれども、英語は横に伸びていくという点に言語間の大きな違いがあります。


言語が異なると、表現できることが違い、それが思考の違いにも繋がります。

言語が違い、思考が違う人に伝えようとすると、シンプルな単語で伝えきれないことがたくさん出てきますね。

OMOTENASHI (おもてなし) とかね。

の第4章 「シニフィアンとシニフィエ」に、「蝶と蛾」はフランス語では「パピヨン」一語という話が掲載されていて、まさにこういうお話でした。

「蝶と蛾」の違いをフランス語で説明するためには、一体どれだけ語らないといけないか、

逆に、日本語独自の言葉を、できるだけ少ない英単語で説明するにはどういう表現ができるか、

ということをやってみると、ものすごい訓練になると思います。

上位概念を伝える

さらには、「処理の流れだけを説明してもわかりにくい」というのがプログラムにはあります。

たとえば

 1$cache_key = 'option-settings';
 2$option_key = 'hoge';
 3$cached_options = Cache::get('option-settings');
 4
 5if (false !== $cached_options) {
 6    return $cached_options[$option_key];
 7}
 8
 9$options = Option::fetchAll();
10Cache::set('option-settings', $options);
11
12return $options[$option_key];

みたいなプログラムがあって、読めば読めれますけれども処理の先頭に

1// オプションを読み取る、キャッシュあり

みたいに書いておけば、読む量が減って把握しやすくなりませんか ? 例があまり良くないかも

結論:コメントはエレガントに書こう

仕様が固まっていて、完璧な設計で完璧コードであれば、コメントがなくてもいけるかもしれません。

実際には仕様が変わることなど常ですし、設計にはミスがつきものです。 そういった経緯を、コメント無しで伝えるのは難しいですよね。

プログラマ歴が長くなる中で、「変数関数名で意味つけてるからコメントなんて不要」と主張していた人が、そのうち 「やっぱりちゃんと書くべき だわー」と軟化する 光景を何度か見ていたりします。


コメントを書く時は

  • クソ細かいコメントをつけ過ぎたり
  • ノリノリで長文になりすぎたり

という点に注意しつつ、処理そのものよりは

  • なぜその処理をしているのか
  • どうしてこうしたのか

という、

  • 処理そのものを説明するよりはメタ情報を
  • ちょっと上の目線から
  • エレガントさを意識

して書いていくと、負担感が少なく、コードの理解を助けるコメントになるのではないか、という感じでした。