Tidy First? ―個人で実践する経験主義的ソフトウェア設計

15章冗長なコメントを削除する

　

コードに書いてあることをそのまま書いてあるコメントがあったら、消そう。

コードの目的は、コンピューターに何をさせたいのかを他のプログラマーに説明することだ。コメントとコードは書き手のあなたにとっても、未来の読み手にとっても、違うトレードオフをもたらす。文章は何でも説明できる。一方で、システムの変更に伴って文章の正確さをダブルチェックする仕組みはないし、コードが進化するにつれてコメントが冗長になるかもしれない。

ある人は、コミュニケーションの義務について視野が狭く、あらゆるルーチンにはコメントがあるべきだ、というような独断的ルールを主張する。その結果、次のようなコメントが生まれる。

getX()
  # Xを返す
  return X

このコメントはコストだけで何もメリットがない。書き手は、読み手の時間を無駄にしただけだ。その時間を取り戻すことはできない。完全に冗長なコメントは消そう。

整頓はよく連鎖する。以前の整頓によってコメントが冗長になることもある。たとえば、このようなコードがある。

if (generator)
    ...ジェネレーターをセットアップするコードのかたまり...
else
    # ジェネレーターがない場合、デフォルトを返す
    return getDefaultGenerator()

ガード節で整頓すると、次のようになる。

if (! generator)
    # ジェネレーターがない場合、デフォルトを返す
    return getDefaultGenerator()

...ジェネレーターをセットアップするコードのかたまり...

最初のコードのコメントは冗長ではない。違うコンテキスト（ジェネレーターがあって、セットアップが必要）の山のようなコードを読んだあと、現在のコンテキスト（ジェネレーターがない）に注意を戻すものだ。しかし、整頓のあとでは、コメントはコードに書いてあることをただ言い直しているだけになってしまった。だから、消そう。アスタ・ラ・ビスタ、アディオス、あばよ。 ...