コードコメントには Why も書いてほしい

背景

有名な @t_wada さんのツイートより。

コードには How
テストコードには What
コミットログには Why
コードコメントには Why not

を書こうという話をした

— Takuto Wada (@t_wada) September 5, 2017

また、それを引用した記事より。

• 「あえてやらなかったこと」をコメントしないと、レビュワーからは「知らなくてやった」と認識される
• 「あえてやらなかったこと」は、ほとんどの場合、ちゃんとコメントしておかないと理解してもらえない
• 「あえてやらなかった」ことを記載すると、レビュワーのコードリーディングの負担が減る
  ― コードコメントにはwhy notを書こう | Zenn

「確かにその通りだ」と頷きながら読みつつも、どこか引っかかりを覚えたので言語化してみる。

そもそもコメントとは、開発者の意図を伝えるためのもの

開発者とレビュワーの間には、必ず情報の非対称性¹が存在する。
なぜなら、コードを書いた人がそのコードに対する意図を持っているためである。
そのため、レビュワーはその意図を知るところからコードレビューを始めなければならない。

この情報の非対称性を解消するためには、例えば以下のような手段がある。

• コメントやドキュメントを書く
• ペアプロやモブプロをする
• アーキテクチャを設計する

このような手段を通して、開発者の意図がレビュワーに伝わり、共通認識ができていると、レビューはスムーズに進む²。
逆に、意図が伝わっていないと、レビュワーの認知負荷は増大し、レビューに時間がかかるようになる。

Why not を書くためには、 Why を書く能力が必要

Why not を書くためには、レビュワーの立場になって考える必要がある。
何らかの制約がわかっている開発者から見るとあたりまえのコードでも、その制約が共有できていないレビュワーからすると変な実装に見えるかもしれない。
そういったことを先読みして、なぜやらなかったか（Why not）をコメントする必要がある。
つまり、開発者は自身の意図だけでなく、レビュワーの意図まで読んでコメントを書く必要がある。

そこまでできる開発者も確かに存在する一方で、そもそも自分の意図を持ってコードを書くことが難しい開発者もいる³。
要件は決まっているが、実装の見通しが立っておらず、その要件を満たすためにひたすらパッチを当てていくようなイメージだ。
このような状態では、開発者が意図を持って実装するのは難易度が高く、なぜこうしたか（Why）をコメントすることも難しい。
そのため、コメントは、何をしているかの説明（What）や、どうやっているかの説明（How）に偏りがちになる。
まずはアーキテクチャという軸を構築する力をつけ、コメントに Why を書く習慣をつけてもらうことが先決かもしれない。

まとめ

レビュイーのレベルに合わせて、求めるコメントの質を変えることが重要である。
コードを読んでいく中でちょっと複雑な処理があるときには、方針（How）を書くだけでも、レビュワーにとっては大きな手がかりとなる。
まずは、レビュワーがコードを読む上での負担を減らすためにはどうすればよいかを考えて、優しさを持ってコメントを書くことが大切だと思う。