プログラム中のコメントの分量（経済学編）

Mizuhiro Suzuki @mizuhiro_suzuki

上司とコーディングの意見が合わず最近ずっとイライラしてたけど、「コメントがたくさんあって500 行のコードより、コメントがなくて100行のコードの方がいい」と言われて、ああもう一生分かり合えないなと吹っ切れた

Ryu Matsuura @ryu_matsuura

@mizuhiro_suzuki それは... お疲れ様です...

Mizuhiro Suzuki @mizuhiro_suzuki

@ryu_matsuura そういう考えの人がいるというのが興味深かったです。 「コードが短い方が読みやすいしレビューもしやすい」と言われ、そんなことないと思うけど、まあ客観的な証拠も出せんしなーとこちらが折れました。チームワークって大変…

Shunsuke Tsuda @ShunsukeTsuda13

@mizuhiro_suzuki @ryu_matsuura コメント沢山の500行より、コメントない(self-documentingな)100行コードの方が良いと思うけど、、そうじゃない理由としたら何やろ？

Mizuhiro Suzuki @mizuhiro_suzuki

@ShunsukeTsuda13 @ryu_matsuura おお、津田くんもそういう考えなのか。もしかしてこれってそんなに少数派の考えじゃないのか…？ 例えば、コメントって何をしてるかだけじゃなくてどういう意図でそのコードを書いたかを記録するものでもあるから、それを任意の他人+将来の自分にわかるようにコードだけで表現するのは無理じゃない？

Mizuhiro Suzuki @mizuhiro_suzuki

@ShunsukeTsuda13 @ryu_matsuura 「記録するものでもあるから」は強すぎるstatementだな。 「記録すらものでもあると私は考えているから」くらいがフェアかもしれない

Ryu Matsuura @ryu_matsuura

@mizuhiro_suzuki @ShunsukeTsuda13 そうですね、コメントは何をしているかというより、どういう意図のもとでそのコードを書いたかを、他人と将来の自分のために残すものだと僕は思っているので、コミュニケーションのツールとして欲しい派ですね

Shunsuke Tsuda @ShunsukeTsuda13

@ryu_matsuura @mizuhiro_suzuki コメント全くなしは極端で無理があるけど、重要な決定の理由などの超最小限に留めるべき派ですね。基本的に共同研究者に配布してるこのスライドのpp.28-29あたりは心がけてます。 stsuda.github.io/teaching/2_Sof…

Shunsuke Tsuda @ShunsukeTsuda13

@ryu_matsuura @mizuhiro_suzuki 大量コメントは親切じゃなくて実際メンテナンスコスト上がる。極端な例だと(と言いつつ今だによく見るけど)、"1_analyze.py"ってコードの1行目にThis code implements X with Yってコメント書かずに、コメント消して"implement_X_with_Y.py"(関数名等も同様)にしてコード自体になるだけ語らせたい。

Mizuhiro Suzuki @mizuhiro_suzuki

@ShunsukeTsuda13 @ryu_matsuura スライドにある思想は理解はできるけど、コード自体に語らせるっていうのが極めて難しいなと思う（コードでしたいことの複雑度にもよると思うけど）。

Mizuhiro Suzuki @mizuhiro_suzuki

@ShunsukeTsuda13 @ryu_matsuura あと、コメントがたくさんあってもメンテナンスコストそんなに上がるかな？って思う。「コメントを最小限にした上でself-explanatoryなコードを書く（＊）」っていう最適化問題を解くことのコストがめちゃめちゃ大きそう。結局（＊）をどれくらいのコストで達成できるかに依る気がする。

Mizuhiro Suzuki @mizuhiro_suzuki

@ShunsukeTsuda13 @ryu_matsuura ただ、正直言って、コメントするのが当たり前だと思ってたから、コメントなしでself-explanatoryなコードを目指して書いたことがない。 いい機会だから、挑戦してみようかなと思う。

Shunsuke Tsuda @ShunsukeTsuda13

@mizuhiro_suzuki @ryu_matsuura たしかに僕が大して複雑なことをするコードを書いてないってところはあると思う。ただ、コード改訂する度にそれに対応するコメントも改訂ってなると、メンテコストが高いかなあ。同じ情報に対応する箇所が複数あると忘れたり不一致が後々起こりがちかと。

にるそん @ohtanilson

@mizuhiro_suzuki self-explanatoryなオブジェクト名+タスクは分割しそもままスクリプト名+繰り返すようなハードコーディングを徹底して避ける->結果行数短いコードが生まれレビューしやすい、長いコメントはレビューコストとメンテコスト上げると教わりました。プロマネの教科書も「簡潔明示的=正義」な主張でした。

Shunsuke Tsuda @ShunsukeTsuda13

@mizuhiro_suzuki @ryu_matsuura これのチャプター7も同じような話だけど、まあ多少タスクによるかも。 scholar.harvard.edu/files/shapiro/…

Mizuhiro Suzuki @mizuhiro_suzuki

@ohtanilson ふむむなるほど、興味深いです。まあその上司はオブジェクトにaとか名前つける人なので論外ですが。 もしよければその教科書教えていただけますか？

Mizuhiro Suzuki @mizuhiro_suzuki

@ShunsukeTsuda13 @ryu_matsuura うーむなるほど、やっぱりタスクによるところが大きいよね。あと、今の自分にはself-explanatoryに思えても、任意の他人や将来の自分にもそうなのかはわからなそう。コメントで補足した方がリスクが小さいと思う。

Mizuhiro Suzuki @mizuhiro_suzuki

@ShunsukeTsuda13 @ryu_matsuura メンテナンスについては、一個一個のコメントの改訂のコストは正ではあるけどそんなに大きくないと個人的には思う。更新し忘れや不一致のリスクは確かにあると思うし、これのコストは確かに小さくないかもしれない

にるそん @ohtanilson

@mizuhiro_suzuki 上司がコーディング力低いとツラいですね。。。アジャイルサムライを最初に読んで、そのあとは某先生にメンターしてもらって「良いコード」を学びました。オブジェクトの話とかは「良いコード(日英)」とかでググるとyoutubeとかドキュメントが沢山あります。

Kohei Kawaguchi=Sunada @mixingale

@ohtanilson @mizuhiro_suzuki どうも、某先生の一人です。こういうのっていろいろな知見をもちよるのが一番大事だと思うので、どこかでコードレビュー会を開いてみるといいかもしれませんね。分野が違うといろいろ異なるベストプラクティスがあるでしょうし。

Mizuhiro Suzuki @mizuhiro_suzuki

@mixingale @ohtanilson そうですね、こういう話、なかなか他の人とする機会がないので勉強会は良さそうです。 妻と話してて、SEとDSでもベストプラクティスは違いそうだなと感じますし、Econの中でも手法によってスタイルが違うかもしれません。

Mizuhiro Suzuki @mizuhiro_suzuki

いろいろ教えてもらって、「コメントなしで100行よりコメントたくさんあって500行のほうがいいけど、コメントは『最低限』にして200行を目指すべき」だなと思った。 twitter.com/mizuhiro_suzuk…

Mizuhiro Suzuki @mizuhiro_suzuki

特に私はコメントは多ければ多い方がいい(多くて損はないやろ)くらいに思っていたけど、メンテナンスコストを過小評価していたと思う。

Mizuhiro Suzuki @mizuhiro_suzuki

この『最低限の』コメントというのはまだ勉強しないといけない。とりあえず、すぐにコメントに頼るのではなく、コードをself-explanatoryにする努力は最初にすべきだと。

Mizuhiro Suzuki @mizuhiro_suzuki

私みたいな弱小アカはツイッターでも建設的な議論ができるみたいだ。楽しかった。