(cache) 「正しく書かれたソースコードにコメントは必要ない」なんて幻想だという話（補足編）

2017-05-20

「正しく書かれたソースコードにコメントは必要ない」なんて幻想だという話（補足編）

　前回書いた「「正しく書かれたソースコードにコメントは必要ない」なんて幻想だという話（ http://d.hatena.ne.jp/t_tutiya/20170519/1495197904 ）」は土屋のブログ記事にしては珍しくはてブやコメント、twitterで反響を幾つか頂きました。その中の幾つかを紹介します。分かっているとは思うけど、サンプルコードはJavaScriptを意識してますがてきとーです。

案１：マジックナンバーを定数化する

MAX_OPAQUE = 1.0f //定数宣言のつもり
if (alpha < MAX_OPAQUE){
 //処理Ａ
}

　"1.0f"に意図を設定すればコメントが不要なのではないか説。うーん、これはちょっと難しいかな……。"MAX_OPAQUE"が正しい変数名だとは思えませんが、どんな名前にすれば意図が説明できるのかちょっと思いつきません。また、数式が複雑化した場合に対応仕切れないのではないかと思います。

案２：条件式をメソッド化する

function isFadeinCompleted(){
  return alpha < 1.0f
}

if (isFadeinCompleted()){
  //処理Ａ
}

　条件式をメソッド化し、そのメソッド名で意図を説明すればコメントが不要なのではないか説。ここではalphaがメンバ変数であると仮定していますが、そうでない場合もメソッド呼び出し時に引数が一個増えるだけです。

　これは一つの回答と言えます。ただ、この条件式がコード上でこの一箇所しか現れない場合に、「（コメントではなく）コードのみで意図を説明する」ためだけにメソッド化すべきなのかには疑問があります（名前空間汚染も起こりますし）。

　実は前回の記事でも当初はこのコードを書いていたのですが「実務で書く時、土屋はこのメソッド化はしないな」と考え、削除したのでした。これが何故なのか理論化できていないのですが、土屋の中では「１行の式を返すだけの処理をメソッド化しない」というルールがあるような気がしています（これはいずれまた検討してみます）。

案３：条件式を一時変数化する

var isFadeinCompleted = alpha < 1.0f

if (isFadeinCompleted){
  //処理Ａ
}

　条件式の実行結果を一時変数に代入し、その変数名で意図を説明すればコメントが不要なのではないか説。

　これは土屋が書かないタイプのコードで、なるほどと思いました。条件式がここ一箇所しか使われていないとしても名前空間を汚染しませんし、「１行の式を返すだけの処理をメソッド化しない」という土屋のマイルールにも抵触していません。また、一般的なコンパイラなら最適化されてオーバーヘッドは発生しないでしょう（もしかしたらlint時に警告が出るかもしれない）。

　ただ、自分が書くかというと、どうかなあ……？　そこまでしてコードで意図を説明しなければならないのか？　と感じます。本来無理筋である（と土屋が思っている）「コード＝ドキュメント」を達成するために、逆に回りくどいことをしているように思えます。

コメント工学のススメ

　「コメントで設計意図を記述すると二重管理になる」という批判をよく聞くのですが、結局なにかしらの仕様書を出力しなければならない以上、どこかで自然言語のテキストを書く事になるのであれば、それがコメントとしてコードに埋め込んである方がトータルの作業コストは下がるのではないでしょうか。

　これは土屋が作家だからなのかもしれませんが、「なぜコメントの（セマンティクスの）記法が検証されていないのか」については強い疑問があります。土屋は「コメントを機械的に書きたい」と常々思っていて、自分の中ではなんとなくなルールを定義して運用しています。これについてはまたいずれ記事にしたいと思っています。

　近年ではコメントにタグを埋め込むことで自動ドキュメント化できる仕組みがありますが、もっとプリミティブな部分で「コメント」を検証する必要があると感じています。コメントは必要だ！　何百行もコメント無しで書くんじゃねえ！　後任者がメンテできねえだろうが！（私情）