1年目から身につけたい! チーム開発 6つの心得

第5章 情報価値の高いコミットをしよう―コードだけではわからない意図を伝える技術

この記事を読むのに必要な時間:およそ 9.5 分

情報価値の高いメッセージを書くコツ

情報価値の高いコミットメッセージをなかなか書けないという場合にはどうすればよいでしょうか。

コミットメッセージの価値を高めるためには,まずコミットメッセージ以外では記録できない情報を示すということ,そして適切な文脈で変更内容をとらえるということが重要です。図2に示した適切なコミットメッセージの例も,その点を強く意識して書かれています。具体的にどういうことなのか,それぞれを詳しく見ていきましょう。

コミットメッセージ以外では記録できない「Why」を書こう

コミットメッセージに書くべき内容は,コメントに書くべき内容と似ています。

  • コードを読んですぐにわかることは,コメントに書かない
  • コメントには,コードを読んでもわからない周辺事情などを書く

具体的な内容としては,ニュース記事の書きかたや,何かを報告するときなどの,5W1Hを考えるとよいです。つまり,

  • Who(誰が)
  • What(何を)
  • When(いつ)
  • Where(どこで)
  • Why(なぜ)
  • How(どのように)

が明示されていると,わかりやすく情報価値の高い記事と言えます。

コミットしたソースコードの差分そのものは,⁠どのように変更したか」を表現した,そのコミットの主題と言えます。これは,5W1Hでは「How」に相当します。

コミットに含まれるそれ以外の情報はすべて,その主題についての補足説明ですが,VCSは補足説明をある程度自動的に補ってくれます。具体的には,誰がいつコミットしたのかはコミットログの情報として自明なので,⁠Who」⁠When」は,書く必要がありません。また,変更したファイル名や関数名などは差分から読み取れるので,⁠What」⁠Where」も書かなくてよい場合が多いです。

そうすると,残るは「Why」なのですが,これはVCSは自動的には補ってくれません。ここまでに述べた情報やコードからも読み取ることのできない情報なので,ここは自分で書かなくてはいけません。よって,コミットメッセージを書くときは「Why」を主軸に置いて考えることが有効だと言えます。この観点から,図2で示した適切なコミットメッセージの例でも「表示状態をもとに戻せるかどうかを検証するため」という「Why」を強調しています。

コミットメッセージは自由記入欄なのでなんでも書けますが,そこでなくても書けることよりは,そこでなければ書けないことを書くように意識しましょう。ほかのことを見ればわかるようなことしか書かれていないと,情報価値の低いコミットメッセージになってしまいがちです。

変更の文脈を意識しよう

適切なコミットメッセージとは,その変更が本質的にどういうものなのかを説明するものです。コミットにも文脈があり,どんなに詳しい説明でも,文脈が適切でないと意味をなしません。

図1のコミットで行われている変更も,どの文脈の話ととらえるかによって次のようにいろいろな説明ができます。

  • JavaScriptだという点に着目するとsetTimeout()を使うようにした」
  • DOMDocument Object Modelを使っているという点に着目すると「DOMを使って要素の表示/非表示を切り替えた」
  • GUIアプリケーションという点に着目すると「UIの表示/非表示を切り替えた」
  • メールクライアントという点に着目すると「起動直後に禁止した操作を,再び許可するようにした」
  • 開発初期の試験実装という点に着目すると「状態を戻せるかどうかを検証するために,一定時間後に状態を戻すようにした」

図1のようなコミットをしたのは,⁠RubyでWebサービスを開発した経験はあるが,jQueryを使わないJavaScriptでの開発はあまり経験がなく,Thunderbird用のアドオンの開発も初めて」という人でした。その経験と照らし合わせると「JavaScriptである」ということだけに意識が向いてしまうのも無理はありません。ただ,その文脈のみでの説明は事実に反してはいなくても,事実のあまりに狭い一面しか言い表せていません。

このような場合は,コミットする前にまずひと呼吸置くとよいでしょう。1つのことに集中していると,ほかのことが見えなくなりがちです。自分が書こうとしているメッセージがどの文脈の話なのかを,いったん退いて客観的な視点で見なおしてみましょう。⁠今何をしていたのか」から「そもそも,何のためにそれをしようとしていたのか」に焦点を移すと,多面的でより適切な説明ができる文脈に気がつきやすいです。

実際に,図2で示した適切なコミットメッセージの例では,⁠GUIアプリケーションの」⁠開発初期の試験実装である」という文脈に沿って,⁠Why」ならびに実際にやっていることの意味合いを示しています。また,Thunderbirdのアドオンという文脈を考えると,開発に使っている要素技術そのものについての言及は不要と考えられるため,関数名やAPIそのものには言及していません。

「Why」以外の情報を付け加える

「Why」をコミットメッセージに含めるだけではまだ伝わりにくい情報もあります。そういった情報を補完するためのコミットメッセージの例をいくつか示しましょう。

変更前後の挙動をbefore:とafter:で説明する

条件分岐の条件式を変えたり,呼び出すメソッドを変えたりといった変更は,変更に伴う影響範囲が一見してわからないことがあります。

このような場合には,変更前と変更後で挙動や処理結果にどのような違いが出るのかを次のような形式で書いておくと,コミットの意図を理解しやすくなります。

before:
   ここで変更前のふるまいを説明する
after:
   ここで変更後のふるまいを説明する

境界値付近注3での振る舞いの変化などが説明されていると,あとから参照するときの資料にもなります。

どこを誤記したのかを説明する

誤記の修正で,⁠Fix a typo」というコミットメッセージにすることはよくあります。しかし,もう一歩進んでどこを誤記したのかを説明しておくと,コミットを見た人が「どこが変わったのか」を理解する手助けとなります。

たとえば,⁠chain」と書くべきところを,うっかり「chian」と誤記していたものを修正したとしましょう。単純にこの変更の前後を示そうとすると,次のように横に並べることを思いつくかもしれません。

chian -> chain

しかし,このようによく似たフレーズは,横に並べても違いがぱっと見でわかりにくいです。こういったものは,次のように変更を縦に並べたほうが見やすいです。また,この例ではさらに,^^で行中の何文字目を間違えていたかを強調しています。

chian ->
chain
  ^^
実行したコマンドを書く

複数ファイルに渡って一括置換するときに,慎重に用意したワンライナー注4を実行することがあります。また,バージョン番号を繰り上げたり,リリースしたり,テンプレートに基づいて新しいコードを生成させたりといった定型的な作業を自動化してある場合に,何かコマンドを実行すると複数のファイルが一気に書き換わることがあります。

たとえば,バージョン番号を繰り上げるmakeのルールが定義済みで,新バージョンをリリースしたあとは必ずmake update-version NEW_VERSION=4.1.1といったコマンドでバージョン番号に関係するすべてのソースを更新するようになっているとしましょう。

そのあと,コミットするときに何も補足情報がなく単に「Bump version to 4.1.1」⁠バージョンを4.1.1に繰り上げた)というコミットメッセージだけを添えていた場合,あとからそのコミットを見た人は,それが自動処理で行われたものなのか手作業で行われたものなのかを知ることができません。そのため,似た作業を別の人がしようとしたときに,無駄に手作業でやってしまい,その結果見落としが発生してしまうかもしれません。

そのような事態の発生を防ぐためにも,何かのコマンドの実行結果をそのままコミットするときは,コミットメッセージに実行したコマンドを含めておきましょう。そうすることで,何を実行してその差分が発生したのかがわかりやすくなります。

注3)
「X以上,X未満」などの条件分岐に対する「X」⁠X-1」⁠X+1」のような,条件に触れるか触れないかの微妙な値が与えられた場合のことです。
注4)
コマンドラインで1行で入力できるようにした,1つ以上のコマンドを組み合わせたコマンド列のことです。

著者プロフィール

足永拓郎(あしえたくろう)

株式会社クリアコード所属。デスクトップや組み込みソフトウェアの自由を求めて活動中。


結城洋志(ゆうきひろし)

株式会社クリアコード所属。Firefox黎明期からアドオン開発を手がけ,業務上もMozilla製品の技術サポートを担当。代表作は「ツリー型タブ」「テキストリンクなど。また,日経Linux誌にて「シス管系女子」を連載中。


林健太郎(はやしけんたろう)

株式会社クリアコード。趣味であれこれと,Sylpheedのプラグインを開発したり,Debianのパッケージをいくつかメンテナンスしている。

Twitter:@kenhys

コメント

コメントの記入