良いCL説明文の書き方

CL説明文とは、コードにどのような変更があり、なぜそのような変更が必要なのかを説明する記録である。今後数百人の開発者は、あなたが書いたCLを探して、過去の記録を見てコードをより深く理解できるようになる。重要な情報がコードだけにあり、説明文がなければ、過去のCLを見つけるのはとても難しいだろう。

最初の行

命令文の形でどのような作業がなされたかを説明し、一度改行をする。最初の行は明確で簡単に書いてコード履歴を探す開発者が一目でわかるようにする。

最初の行以降、本文にはCLが解決した問題を作成し、なぜこれが最善の解決策なのかを説明する。解決策に技術的な欠点があれば、これも含める。問題トラッキングナンバーや参考文書を付け加えても良い。小さくてマイナーなCLにも必ず背景の説明を含める。

「バグ修正」はCL説明文としては物足りない。

なども同じだ。前述のものは実際に存在するCL説明文だが、説明文を作成する目的に適合しない。

良い説明文は、CLが何をしているのかを最初の行に説明する。本文にはどの問題を解決するのか、なぜこのように解決したのか、そしてコードの説明もあり、そのCLの背景説明や今後の発展方向を含めることもできる。

コードレビューを経てかなり多くのものが変わる可能性がある。最後に、コードをマージする前の説明文に変更が反映されていることを必ず確認する。