この文書はCode Healt: Providing Context with Commit Messages and Bug Reportsの翻訳です。
罠にかかった。訳がわからない仕掛けに取り囲まれている。必死に手がかりを探し、製作者の当初の計画を見つけ出した！この罠を生み出した作業指示書にはこう書かれている、「各種の修正」。なんてこった。
他のエンジニアのコードを読むことはときに考古学的遠征に似て、奇妙ですばらしい記述に満ちている。 コードは常にある目的を持って書かれている。しかし、その目的がコード自体を見ただけでは不明瞭なことも少なくない。 このナレッジギャップには、なぜこのチェンジ1が必要なのかを説明したコンテキストを文書化することで取り組むことができる。コードコメントもコンテキストを提供するが、コメントだけでは十分でないこともある。
コンテキストを示すには2つの鍵になる方法がある:
コミットメッセージ
-
コミットメッセージは最も簡単で最も見つけやすくコンテキストを提供する方法である。不明瞭なコードに出会ったとき、そのコードが導入されたときのコミットメッセージを確認することは、そのコードが何を意図しているのかに関するより多くの洞察を得る素晴らしい方法である。
-
コミットメッセージの最初の行を独立しているように書くこと。 GitHubのようなツールはコミットリストページで最初の行を表示する。独立した最初の行によってコード履歴をより早く掴むことができ、ソースファイルがどのように時間とともに変遷したのかを素早く理解することができる。
例
Add Frobber to the list of available widgets.
This allows consumers to easily discover the new Frobber widget and
add it to their application.
バグレポート
-
バクレポートを使うことによってバグ/機能/リファクタリングの全体ストーリーを追跡することができる。 オリジナルの障害の記述といったコンテキストや、チーム内でのデザインディスカッション、障害を解決するためのコミットなどが、バグレポート2には追加されていく。すべての関連するコミットを一箇所で見ることを容易にし、他者からも特定の問題のステータスを容易に追跡することが可能になる。
-
ほとんどのコミットはバグレポートを参照するべきだ。 ただし、単独のコミット（例えば、1回きりのクリーンナップや小さな計画外の変更など）には、ソースチェンジとそのデスクリプションにそれ自体のコンテキストはすべて含まれているため、バグレポートは不要である。
情報豊富なコミットメッセージとバグレポートを協調させよう。 それらは異なった観点からコンテキストを提供する。そういったコンテキストは君自身にも有益だということを心に留めよう。それらによって、君が先週、先クォーター、さらには昨年した仕事を簡単に思い起こすことができる。未来の君は過去の君に感謝するだろう！