jfluteの日記 このページをアンテナに追加

2018-06-25

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

|

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

講演で、ソースコードのコメントに関して、
話をするときのお約束パターンがこちらです。
// ライターを閉じる
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(); // ブラジルに勝つ!
    serbla.returnToHotel();
    serbla.sleep();
    serbla.wakeUp();
} catch (BoroBoroException ignored) {
    // ショックすぎて何事もなかったかのように振る舞う
}
確かにおうむ返しなので、
別に無くてもいいものではありますが、
まあ、これはこれでデザインです。

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

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

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

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

カテゴライズしたくて、
おうむ返しっぽいコメントを書くことも
あるかもしれません。
// W杯でブラジルと試合をする
serbia.moveToStatium();
serbia.warmingUp();
serbia.winBrazil();

// 試合後にホテルで休む
serbla.returnToHotel();
serbla.sleep();
serbla.wakeUp();
serbla.goodMorning();
三つの処理をまとめて何々...
四つの処理をまとめて何々...

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

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

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

どちらかと言うと話

だんだん、"おうむ返しかどうか?" が問題というより、
"オートマティックで価値のないコメントかどうか?"
ということがポイントだと思えるようになってきました。

"価値がある、ない" というのは、
そのコメント自体の特性で決められるものではなく、
そのソースコード全体の特性、想定される読み手の状況、
などなど、コメントが置かれている状況が左右すると。

おうむ返しでも価値がある場面なら別に良いわけです。
価値を考えずにオートマティックに書きまくって、
ノイズコメントになってしまうと良くないわけで。

また、時間の問題もあります。時間は有限です。
おうむ返しコメントも書くの大変そうです。

その労力を背景や理由を書く方に使おう

そういうニュアンスでもあります。
例えば、背景や理由などがちゃんと書いてあった上での、
おうむ返しコメントであれば、そこまで問題にしません。

(でも、"そのコメントを書く時間省略して先に進んでいいよ"
くらいは言うかもしれません...)

(また、"そういうコメントを書かないといけない"
と勘違いしてるかもしれないので、"別に無くてもいいですよ"
くらいは言うかもしれません...)

...

こちらの記事もすごく参考になりました。
今回のブログを書くきっかけになった一つです。

Rubyコミッター・Yuguiに学ぶ、
コードに書くべき「適切なコメント」と「適切な場所」
 | エンジニアHub
 
...
 
そのコメントで伝えたいことはなに?

と聞かれて、些細な理由でもいいので、
明確に答えられるコメントを書きましょう。

f:id:jflute:20180625135635j:image
トラックバック - http://d.hatena.ne.jp/jflute/20180625/repeatablecomment