オートマティックおうむ返しコメントより背景や理由を

まさにおうむ返しコメント

講演で、ソースコードのコメントに関して話をするときのお約束パターンがこちらです。

// ライターを閉じる
writer.close();

見ればわかります！

writer が .close() してますから。 writer, close という単語もほとんどの人が知っていますし、知らなくても調べれば良いレベルです。

仮に、変数名とかメソッド名に文字数制限があったとしたら、意味があるかもしれません。

// ライターを閉じる
w.cl();

確かに...時にそういう場面があって、そういうコメントを書くこと自体は問題ではありません。ちゃんと理由があるから...

ただ、少なくとも今の時代、そのような制限はあまりないでしょう。

...

さて、もうひとつ。

// 年齢に0を設定
setAge(0);

見ればわかります。

しかも、"0" って値までおうむ返ししているので、こんな未来を想像してしまいます。(仕様変更やバグ修正が発生して...)

// 年齢に0を設定
setAge(1);

具体的な値をコメントに書くのは、さすがにやめるとします。

// 年齢を設定
setAge(0);

戻ってきました、やはり見ればわかります。

...
...
...

オートマティックおうむ返し

まあ、時に、変数名やメソッド名からやっていることが読み取れないようなケースで、おうむ返しっぽいことをするのは仕方ないでしょう。

時に "自然言語の業務名" とプログラム上の処理が、直感的に結びつかないケースもあるかもしれませんし、どうしてもそれを直すことができない、という状況もあるかもしれません。別にそれはそれで良いです。考えて判断してますから。

そうではなく...

必要かどうかを考えずに、機械的にただひたすらおうむ返しする

というコメントがポイントです。

そういったコメントは、不要なだけでなく、"ソースコード上のノイズ" になるので、可読性に悪影響すら与えていると言えます。なので削除した方が良いです。

それよりも、

「0 を設定するというのは、業務的にどういう意味があるのか？」

「なんのために、ここで 0 を設定しているのか？」

の方が知りたいことです。

背景や理由を書こう

月並みですが、コメントは背景や理由などを書きましょう。

それってつまり...

コードから読み取れないもの

(もしくは、読み取りにくいもの)
を書くということです。

...

例えば、writer.close() において...

「通常、そのタイミングで close() は、あんまりしないものだけど、なぜだろう？」

というように読み手が思うような特殊な呼び出しであれば...

writer.close(); // 驚かせたくてこのタイミング

ということが書いてあれば、
「ああ、驚かせたかったんだ」と理解できます。

...

また、setAge(0) であれば...

setAge(0); // ここで生まれ変わる

ということが書いてあれば、「ああ、また人生やり直すのか」と理解できます。

ただ、なんでここで生まれ変わるんだろう？という疑問も生まれたりもするので...

setAge(0); // キャンペーンで永遠の命を得たので、ここで生まれ変わる

ということが書いてあれば、「ああ、火の鳥サービスなんだ」と理解できます。

...

コメントは、人間のために書いています。その人間が何を知りたいのか？それを想像しながら書くものです。

オートマティックなおうむ返しコメントは、本当に大切なコメントを、意味のないコメントで埋もれさせてしまう可能性があります。

クラスやメソッドでうまくカテゴライズするなど、あまりコメント書かなくてもわかるようにする、という工夫もそれはぞれで心がけることですが、スキルの問題、時間の問題、費用対効果の問題、色々と事情はありますから、どうせコメントというソリューションを使うなら、知りたいことを書きましょうと。

機械的にできることに価値なし

「何も考えずに "コメントはこう書けばいい" という機械的なルールが欲しい、あるべきだ」

という声も時々聞きます。

ですが、先ほどの通り、コメントは人間のために書いています。後でソースコードを読む人間の要求は、なかなか定型化できません。

コメントはデザインなのです。
　=> プログラマーに求められるデザイン脳

もし、機械的なルールでコメントが書けるとしたら、そのコメントを書くのは人間である必要はないでしょう。そういった機械的に導出できるのであれば、自動生成するなどした方が良いでしょう。

プログラマーは、単なる作業員ではありません。考えた結果に対してお金をもらっていると言えます。

考えることをやめたプログラマーに価値はありません

初心者時代の習慣が残ってる!?

しかしながら、なぜこのようなおうむ返しコメントをよく見かけるのでしょうか？

ひとつ思ったのは、初心者時代の勉強用のコードにおいては、そのようなコメントを書くことがあります。

まだそもそもプログラムの理解が浅く、つどつど何をやっているのか解説しないと、すぐにわからなくなってしまうからです。解説を入れることで覚えるというのもあります。英語の勉強をしているようなものです。

それがそのまま習慣化して、業務のプログラミングにおいても、おうむ返しになってしまうのかもしれません。

jfluteは初心者の方のレビューをする機会も多いのですが、必死に学ぼうとするためのコメントをよく見かけます。研修のコードであれば、それ自体の指摘もしません。ただ、ある程度進んできたら、もうそろそろ要らないんじゃない？って、言うように...しようかなって思い始めました(^^。(もうそろそろっていつだろう...!?)

言い訳コメントも良い訳

時に、どうしても様々な事情で、"普通" の実装ができなかったとしたとき、言い訳のようなコメントを書きたくなることがあります。

// 開発期間がワールドカップ真っ最中で、
// セルビアがスイスに逆転負けをして、
// 残るブラジル戦で勝たないといけない状況になり、
// チーム全員へこんで集中できなかったので、
// もう無理やりなロジックでいったんリリース。
// (本当は、ああしてこうしたほうが良いと思う)
//  by jflute (2018/06/25)
logic.executeMuriyari();

すごく言い訳がましいですし、世の中の「そんなコメント書くくらいなら...」的なプレッシャーもあって、ちょっとためらってしまうかもしれません。

でも...

一番良い解決ではないかもしれませんが、七番目の解決よりは二、三番目の解決の方が良いです。後からコードを読む人からしたら、言い訳でも何も情報がないよりは100倍マシです。仮にその言い訳が納得いかないものだとしても、状況を知る上で、その後何かを判断する上で、その言い訳コメントはなんだかんだ役に立ちます。何も書いてなかったら疑いしか発生せず、身動き取れなくなる可能性があるわけですから。

...

ちなみに、jfluteは、こういういった言い訳コメント書くとき、しばしば名前と日付を入れたりします。(特に別の人がメンテするだろうコードにて)

こういうときは技術以外の事情も絡みやすいので、誰が書いたか？ってのも判断要因の一つになりがちです。いつ頃の話なのか？ってのも同様です。

gitの履歴を見ればわかることもありますが、そんなコメントを読むということは、切羽詰まっている可能性も高いですから、履歴を探しに行く手間を省くのもそうですし、わざわざ履歴を見に行ったりしないかもですし。"悩むようだったら、すぐ俺に聞いてね" って感じで。

...

また、チケット管理システムの方で、あれこれやり取りがある場合なんかは、もうチケットへのURLをまんま貼り付けたりします。最悪、それだけあれば読み手は状況を把握できます。

// https://.../WOLRDCUP_SERBIA-623
logic.executeMuriyari();

強調はあるかもしれない

強調という意味合いで、おうむ返しっぽいことをすることもあるかもしれません。

そこで、その処理をしていることが重要で、目立たせないために書いてあるときなど。(周りの処理に比べて特に重要で、読み手にその処理があることを主張したいとき)

try {
    serbia.moveToStatium();
    serbia.warmingUp();
    serbia.winBrazil(); // ブラジルに勝つ！
    serbia.returnToHotel();
    serbia.sleep();
    serbia.wakeUp();
} catch (BoroBoroException ignored) {
    // ショックすぎて何事もなかったかのように振る舞う
}

確かにおうむ返しなので、別に無くてもいいものではありますが、まあ、これはこれでデザインです。

"コードから読み取れない強弱" を、コメントの存在自体で表現しているので、機械的なものではありません。(ソースコードは、HTMLみたいに、フォントサイズやフォントカラーで装飾できないので)

「書きましょう」というほどのものではないですが、「消しましょう」というほどのものでもないです。

読み手のことを考えた結果であれば、この辺のデザインは自由で良いと思います。jfluteも時々書きますよ。(もうちょい派手に書くかもだけど)

カテゴリはあるかもしれない

カテゴライズしたくて、おうむ返しっぽいコメントを書くこともあるかもしれません。

// W杯でブラジルと試合をする
serbia.moveToStatium();
serbia.warmingUp();
serbia.winBrazil();

// 試合後にホテルで休む
serbia.returnToHotel();
serbia.sleep();
serbia.wakeUp();
serbia.goodMorning();

三つの処理をまとめて何々...
四つの処理をまとめて何々...

完全におうむ返しとは言えませんが、コードから読み取れなくもない情報です。でも、読み取るのにわずかに時間が掛かりそうです。個々の処理を読んで抽象化をする必要があります。

読み手の読む労力を少し軽減させるためのコメントと言えるでしょう。それを狙って書いているのであれば、価値のあるコメントと言えます。

メソッドにして表現するというやり方もありますが、ひたすら細かくメソッドにするのもキリがなく、それはそれで見づらくなる要因と考えて、バランスを取ってコメントで表現することもあるでしょう。