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

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

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

「良いコード」の次は「良いコミュニケーション」だね


コミュニケーション……毎日居酒屋で一杯やりながらってやつですね!?


そういう意味じゃないって。一緒のチームで開発するうえで大事なのは,それぞれのメンバーがどういう仕事をしているのか,この部分は誰がどうやって作ったのか,これは何のためにあるのか,そういった開発に関するさまざまな情報を適切に共有することだよ

Redmine注1とメールじゃだめなんですか?


それらももちろん重要だけど,VCS自体もコミュニケーションのためのツールなんだよ

えっ,VCSでコミュニケーションするんですか!?


ああ。VCSの使い方の最小単位といえば「コミット」だけど,そこにどんな情報を込めるかによって,意図の伝わりやすさは大きく変わるんだ。VCSは,使いかたによって宝の山にもゴミの山にもなるんだよ

注1)
代表的なITSIssue Tracking Systemです。

情報価値の高いコミットメッセージを書こう

コミットメッセージは,開発を継続していくうえでとても貴重な情報源になります。しかし,初級者,あるいはそのプロジェクトに明るくない人は,情報価値の低いコミットメッセージを書いてしまいがちです。たとえば,図1はあるコミットの詳細をgitshowで表示したもので,コミットメッセージにはsetTimeoutを使うようにした」と書かれています。しかし,setTimeoutを使ったこと」はソースコードの変更内容から明らかであるため,ここでは重要ではありません。ほかの開発者がこのコミットを見たとき,本当に得たい情報はsetTimeoutという関数を使って『何をしたかったのか』⁠ではないでしょうか。

図1 情報量が少ないコミットメッセージ

commit xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Author: Taro Yamada <yamada@example.com>
Date: Fri Dec 19 14:58:05 2014 +0900

    Use the function 'SetTimeout'

diff --git a/content/messenger-overlay.js b/content/messenger-overlay.js
index 9035704..cc54aa0 100644
--- a/content/messenger-overlay.js
+++ b/content/messenger-overlay.js
@@ -6,5 +6,8 @@
     document.addEventListener("DOMContentLoaded", function onDOMContentLoaded(aEvent) {
        document.removeEventListener("DOMContentLoaded", onDOMContentLoaded);
        document.documentElement.style.visibility = "hidden";
+       setTimeout(function () {
+            document.documentElement.style.visibility = "";
+       }, 1000);
  });
  })();

このように,有効な追加情報が得られない,情報量が少なすぎるコミットメッセージはよくあります注2が,本章ではこのようなコミットメッセージのことを情報価値が低いと表現することにします。

注2)
以降の説明ではVCSとしてGitを使用しますが,ほかのVCSでも同様のことはできます。

コミットメッセージの情報価値

setTimeoutという関数を使って「何をしたかったのか」⁠それを把握するためには,このコミットの背景を知る必要があります。

これは,第3章や第4章でも例に挙げたアドオンtbforce-auth-at-startupの開発中のコミットです。図1におけるdocument.documentElement.style.visibility= "hidden";の個所が「UIを非表示にする」という処理です。setTimeoutの個所は「1秒後にUI要素を表示にする」という処理ですが,⁠認証成功」の動作が抜けていることからわかるように,これ自体はアドオンの目的である「Thunderbirdの起動時にUIを非表示にしたあと,すべての受信サーバへの認証を試行して,成功した場合だけUIを表示する」を直接的に達成するものではありません。

実はこのコミットは,⁠実際にそのようなアドオンを開発できるのか?」という要素術の検証段階で行われたものでした。具体的には次のような場面です。

  • UIを非表示にできることが実際に確認できた
  • UIを再表示できるかを実験するため,ひとまず1秒後に再表示処理を行ってみる

このような事情は,コードからは読み取ることができません。そのため,ドキュメントやコメントなどで説明を補う必要があります。しかし,コミットメッセージもまた,そのような情報を書き記すための場所として使うことができます。

以上を踏まえると,適切なコミットメッセージは,たとえば図2のようなものになるでしょう。本章ではこのようなコミットメッセージのことを情報価値が高いと表現することにします。

図2 適切なコミットメッセージ

Show UI again with a delay to confirm its visibility is certainly restorable
(表示状態をもとに戻せるかどうかを検証するために,一定時間の遅延のあとでUIを再表示する)

著者プロフィール

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

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


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

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


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

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

Twitter:@kenhys

コメント

コメントの記入