コミットへのコメントサービス導入事例のご紹介

はじめに

昨年12月、クリアコードは「コミットへのコメントサービス」を始めました。このサービスは、「みんながみんなのコードを読む」文化づくりを支援するサービスです。どうして「みんながみんなのコードを読む」文化づくりを支援するかというと、よいコードを書くことを当たり前にするためにはまず「みんながみんなのコードを読む」文化にすることからはじめるのがよいという考えからです。

今年2月からミラクル・リナックスさんに対してこのサービスを提供しています。この導入事例を通じて、コミットへのコメントサービスがどのようなものなのかを紹介します。

開発チームの紹介

はじめに、コミットへのコメントサービスを利用しているミラクル・リナックスの開発チームを簡単に紹介します。この開発チームは、デジタルサイネージやサーバー監視に関するソフトウェアを開発しています。開発は次のプロセスで進めています。

BTSにバグや新機能を報告
開発者が手元でバグや新機能の内容を確認し、ソースコードを修正
ソースコードを修正したらBTSにパッチをアップロードし、自分以外の誰かにレビューを依頼
レビューが通ったらリポジトリ（Subversion）にコミット
コミットしたらコミットしたリビジョンをBTSに書き込み、バグをクローズ

このプロセスでは開発者が書いたコードは誰か別の人が必ず読む仕組みになっています。しかし、みんなが読むわけではありません。

パッチをBTSにアップロードする前の状態は共有していません。開発者ごとにgit-svnやquiltを使って、手元で作業を進めています。

導入の経緯

次に、ミラクル・リナックスの開発チームがどうしてこのサービスを導入したのかを説明するために、導入までの経緯を紹介します。

最初に、開発チームのメンバーにサービス内容を紹介しました。開発チームのメンバーからは、「他の人がパッチをアップロードするまでどうやって試行錯誤しているかに興味がある」、「コードを読んでもらえるとうれしい」など、コミットへのコメントサービスの導入に前向きな意見をいただきました。また導入による次の効果を期待されていました。

作業途中の状況を共有できるようになる
- これまでは間違った方向に進んでいても、レビューで指摘されるまで気がつかないケースがあった
コーディングスタイルを共有できるようになる
- コードのスタイルに統一感がないケースがあった

開発チームの後押しもあり、経営層のサービスに対する理解も得られ、2月からサービスをはじめることになりました。現在はこの開発チームのうち4名が「みんながみんなのコードを読む」ことに取り組んでいます。

以上が導入までの経緯です。いくつか認識している課題があり、このサービスによりそれらを解決できそうだという期待があったことがサービス導入の決め手になりました。

導入後の流れ

それでは、サービス導入後はどのように進めたかを紹介します。導入直後のみの作業と日々の作業をわけて紹介します。

導入直後のみの作業
- コミットメールの配送開始
- 導入研修の実施
日々の作業
- コミットを読む
- 読んだことを記録

導入直後のみの作業：コミットメール配送と導入研修

導入後すぐに、開発者が手元の変更をコミットするとコミットメールが流れるようにしました。コミットメールの設定方法は今後ククログの記事でまとめる予定です。

その後、導入研修を実施しました。導入研修では、コミットメールを読む目的の説明とコミットメールを読む練習を行いました。導入研修は、DevLOVE 2012でのセッション「リーダブルコードを読んだ後」に沿った内容です。導入研修では、コミットを読みやすくするためにはどうすればよいか参加者全員で議論し、翌日からどのようにコミットするのか、その方針を共有しました。

日々の作業：コミットメールを読む。読んだことを記録する。

導入研修の翌日からコミットメールを開発チームのメンバーとクリアコードの担当者が読み始めました。クリアコードの担当者はコミットメールを読んで気づいた点があればコメントしました。コメントはコミットを読みやすくするためのアドバイスが中心でした。例えば、より変更内容が伝わるコミットメッセージの書き方や、よりわかりやすい名前の提案、読みやすいコードの書き方の提案などです。もちろんtypoなど誤りがあった時もコメントします。

一日の終わりに、その日読んだコミットメールについて次の記録をつけます。

コミットメールの何割読めたか（割合は個人の直感）
印象に残ったコミット

「何割読めたか」を「正確な値ではなく直感でよい」としているのは正確な値が必要ないからです。値は傾向を把握するために使うだけなので概算値で十分です。必要のない情報を取得するために日々の作業の負荷があがってしまわないように直感でよいことにしました。

ふりかえり

導入後、ある程度経った頃にこのサービスについてふりかえる会「ふりかえり」を何度か行いました。

ふりかえりは開発チームとクリアコードの担当者が一同に会して行います。コミットメールを読んだりコメントしたりする上での疑問や課題を共有し、解決策を検討することが目的です。導入から3週間が経過した時に最初のふりかえりを行いました。次に、導入から6週間が経過した時に2回目のふりかえりを行いました。2回目のふりかえりでは収集したデータから、「みんながみんなのコードを読む文化」がどれくらい根付いたか測定し、見つかった課題に対しては対策を検討しました。

3週間経過時のふりかえり

導入研修から3週間の状況は次のとおりでした。

1日あたり50通から100通のコミットメールが流れている
開発チームのメンバーは平均すると50%程度のコミットメールを読んでいる
クリアコードのメンバーだけでなく開発チームのメンバーもコメントしており、コミットメールを契機にした議論が活発だった
日々の記録の「印象に残ったコミット」はあまり記録されなかった

開発チームのメンバーからコミットメールを読むようになってからの変化について次の意見が挙がりました。

パッチが細かくなって機能修正とインデントの修正が分けられるようになったのはよい効果だと思う
読む側としては変化を感じないが、書くときはコミットを小分けにするようになった
- 以前なら2,3個の大きなパッチだったものが、10個ぐらいの小さなパッチになった
パッチは以前よりも小さくなった
- 小さくなったことで読みやすくなった
コミットメッセージを書くことに時間がかかるようになった
コミットメールを読む人の立場を考えると、コミットメッセージは詳しく書いてあるほうがわかりやすいと思うが、どこまで詳しく書くべきか悩む

コミットメールを読むこと、気づいたことにコメントすることが当たり前という文化ができつつありました。ひとつのコメントから議論が盛り上がることもよくありました。また、読まれることを考えてコードを書くことが習慣となってきました。

一方、うまくいかないこともありました。読みやすいコミットについて判断がつかなかったり、読みやすくするためにどうするのがよいかは試行錯誤していました。

この時、読む人の立場という観点に関連して、これまで困ったことがあるケースが1つ挙がりました。研究開発したソフトウェアを製品化する過程で、なぜ研究開発時にそのようなコードを書いたのか理由がわからず、製品化するときに判断できないというケースです。研究開発でプロトタイピングしている場合でも、意図を伝えるよう意識して欲しいという要望です。これについては、実際に研究開発している開発者がコミットメッセージを詳しく書くことでコードの意図が伝わるか試すことになりました。

日々の記録に印象に残ったコミットを書かない理由として、自分のプロジェクトのコミットメールだと新たな気づきが少ないとの意見が挙がりました。この対策として自分が関わっていないプロジェクトのコミットメールも流すようにしました。またHTMLメールだと、特定のメールクライアントで表示がくずれるケースがあることがわかったため、テキストメールに変更することにしました。

6週間経過時のふりかえり：データの分析

コミットメールを読み始めてから6週間が経過したときに2回目のふりかえりを行いました。この間にクリアコードではコミット数や読めた割合といったデータを収集し、分析ツールによって期待される効果がでているか検証しました¹。期待される効果がみられないものについては、それが問題あるものかどうか検証し、問題だと判断したものについては、対応策を検討しました。

主に次のデータを収集し分析しました。データは月毎に集計し、開始月（2月）と翌月（3月）との間の傾向を分析しました。

コミットサイズ
コミット数
コメント数
コミットメールを読めた割合

コミットサイズ

コミットサイズは徐々に平均値が小さくなる傾向を期待しています。わかりやすいコミットはコミットの内容が小さくまとまるからです。読みやすくすることを意識してコミットするようになると、コミットのサイズが小さくなるはずです。

データを分析すると、デジタルサイネージ、サーバー監視のどちらのプロジェクトでも、サービス導入後にコミットサイズが小さくなっていました。また、興味深いことに、導入開始翌月は、それぞれのコミットサイズの平均値が非常に近い値となっていました。同じ開発言語（C++）で書かれていること、適切な粒度でコミットできていることが理由だと考えられます。コミットサイズについては、期待される効果がでていることが確認できました。

一方、コミットサイズだけを指標として扱うことに対する懸念が挙がりました。コミットサイズが小さければ小さいほうがよいのであれば、意味もなくコミットを分割することにつながってしまうのではないかということです。つまり、コミットサイズだけではなくわかりやすさも加味した分析を行う必要があるということです。このような分析をどのように行うかはこのサービスの現在の課題です。

コミット数

期間内の開発の規模が同じだった場合、コミットサイズが小さくなることに反比例してコミット数が増えることを期待しています。これは、全体で書くコード量が変わらないからです。「コミットサイズ × コミット数 = 開発規模（コード量）」という式が成り立ち、「開発規模」が変わらず、「コミットサイズ」が小さくなった場合は、「コミット数」が増えるはずです。

データを分析すると、コミット数の増加傾向はみられませんでした。これは、どちらのプロジェクトも開発規模が開始月と翌月で異なったことが原因でした。コミットのコメントサービスを始めたことによって、コミットするときに考えることが増えて時間がかかるようになっているとの意見はありましたが、開発量に影響を与えるものではなかったようです。そのため、今回はコミット数は有意なデータとはなりませんでした。

コメント数

コメント数は増加する傾向を期待しています。これは、コミットメールを読むことに慣れてくると、より多くのコミットを読むことができるようになり、気になることが増え、コメントする機会が増えるだろう、という理由からです。

開始月と翌月を比較するとコメント数は若干減少する傾向にありました。これは期待した傾向ではないので別途検証しました。

コミットメールを読めた割合

コミットメールを読めた割合は増加する傾向を期待しています。コミットメールを読むことに慣れる、読みやすいコミットメールが増える、この2つの効果によって1つのコミットメールをより短い時間で読めるだろう、という理由からです。

開始月と翌月を比較すると、読めた割合が全員減少していました。これは期待した傾向ではないので別途検証しました。

読めた割合を分析しているときに、印象に残ったコミットに関するコメントが記録されない日が増えていることにも気づきました。これは期待した傾向ではないので別途検証しました。

6週間経過時のふりかえり：期待した傾向が見られない項目の検証

期待した傾向が見られなかった次の項目についてはその原因を究明し、対策を立てるため、なぜそのような結果になったのか仮説を立てて検証しました。

コミットメールを読めた割合が減っている
コメント数が減少している
日々の記録のコメントが書かれていない

コミットメールを読めた割合が減っている

減った要因として以下の5つの仮説を立てました。

忙しくて読めなくなった。
コミットメールを読んでもメリットがないと感じている。
コミットメールはHTMLメールのほうが読みやすかった。テキストになり読みにくくなった。
コミットメールの読み方を変えた。たとえば、ひとつひとつ時間をかけて読むようになった。
自分が関わっていないプロジェクトのコミットメールを読むのが辛い。
コミットメールの量が多くなったので、コミットメールを読み飛ばすようになった。

メンバーに確認したところ、1.、4.、6.に該当することがわかりました。6.のケースでは、朝一番に大量のコミットメールが届いていると読む気になれず、読めた割合が減っていました。4.のケースでは、コードレビューを集中的に行なう時期だったのでコードレビューと同じモードでじっくりと時間をかけて読むようになった結果、読める量が減っていました。また読めた割合をつけていると100%が求められているように感じ、読めていないときは挫折感があるという意見も聞かれました。

これらの対策として、読めた割合が100%になることを目指すものではなく、毎日一定の時間コミットメールを読む習慣をつけることが目指すべきところであることを再確認しました。また読む時間を確保する方法として、毎日少なくとも1回コミットメールを読む時間をとることを提案しました。

コメント数が減少している

コメント数が減少した要因として以下の仮説を立てました。

読む割合が減ったのでコメントする機会が減った。
コメントをするのに時間がかかるのでコメントしなくなった

1.は事実として読む割合が減っているので正しいと言えます。2.については、メンバーに確認したところ、気になることがあったときに、コメントせずに流しているケースがあることがわかりました。コミットメールを読んで、こうしたらいいのになという案は浮かぶが、なぜそれがよいかパッと出てこないときにコメントすることを諦めてしまうことがあるようです。

クリアコードでは、コミットメールにコメントする際、次の3点を含めることにしています。

どこが気になったか
なぜ気になったか。（例：○○だから読みにくい。）理由がなければないことを表明する。
改善案があるかないか。改善案があればそれを書く、なければないことを表明する。

このルールに従えば、理由や改善案がない場合でもそう表明すればよいだけなので、コメントしやすくなります。理由が浮かばないという理由でコメントすることを諦めないようにするために、コメント時にこのルールを参考にすることを提案しました。

日々の記録のコメントが書かれていない

読めた割合を記録する際、あわせて印象に残ったコミットについてコメントすることになっています。しかし、読めた割合は記録されている日でも、印象に残ったコミットについての記録されない日が多くなりました。コミットメールを読むことに慣れてきて、よいコードに気づく機会がさらに増えてくれば、気になったコメントを記録する日が増えることを期待していました。しかし、逆の傾向になっていました。どうして逆の傾向になっているか、次の仮説を立てました。

書くことがなくなった。
書く目的がわからない。
何を書いていいかわからない。

メンバーに確認したところ、そもそもの書く目的が明確でなく、書くこともなかったので、次第に書かなくなったということでした。一方で、印象に残ったコミットが記録されているとそれに対する反応はよくありました。そのため、読み物としては人気のあるコンテンツと言えます。ただ、自分が書くとなるとなかなか書けないという状況であることがわかりました。そこで、まずどのように書けばよいか、参考として、クリアコードの担当者が書く日々の記録もコミットメールで流すようにしました。また、記録する内容を気になったコミットに限定せず、コミットやプロジェクトに関連していれば何でもよいことにしました。

その他

ふりかえりを通じて、コードの書き方に悩んでいることがわかりました。よいコミットとそうでないコミットの基準が固まっていないため、コミットをどのような単位で行えばよいか考える時間が増えたようです。そこで参考としてクリアコードが行なっているフリーソフトウェア開発のコミットメールをこの開発チームにも流すようにしました。

ふりかえりの重要性

ふりかえりは2回とも2時間にも及びました。コミットメールを読むこと、読みやすいコミットを心がけることは開発チームにとって、新しい習慣です。そのため、これまでの開発スタイルに少なからず影響を与えます。取り組むことによって、上手くいかないことや、迷ったりすることが出てくるので、それを解決していくためには、チーム内で課題を共有し、改善策を検討・試行していくことが不可欠です。定期的なふりかえりは課題を共有したり改善策を検討する場となるので重要です。

サービス提供側としてのクリアコードのふりかえり

ミラクル・リナックスの開発チームとのふりかえりを踏まえて、クリアコードではサービス提供者としてこれまでをふりかえりました。

導入教育について

コミットへのコメントサービスの目的を伝えることはできました。一方で、ふりかえりでは読みやすいコミットに関する質問が多くあったので、導入教育の段階でよいコミットとはどのようなものか伝える必要があることがわかりました。伝える方法として、たとえば、よいコミットと悪いコミットの例をあげることによってよいコミットを伝えたり、よいコミットについて議論することが考えられます。

コミットメールの配信について

開発チームのコミットメールだけでなく、開発チーム以外のプロジェクトのものも最初から流すようにしたほうがよいことがわかりました。自分たちのプロジェクトだけがコメントされるのではなく、他のプロジェクトがコメントされるのを見ることによって、コメントによるコミュニケーションの仕方や判断基準を考える機会になります。その場合、最初から多くのコミットメールが流れることになるので、コミットメールの読み方（読む時間を確保する方法など）を紹介する必要がありそうです。

日々のコミットメールへのコメントについて

コメントすることによって相手との関係がギクシャクするのではないかと心配していましたが杞憂でした。しかし、コメントしても返事がないときはコメントが適切でなかったのではないかと不安になることがありました。導入研修で、コメントされたら返事するよう伝えるのがよさそうです。

また、気になったことがあっても、理由や改善案が思いつかずコメントしないケースがクリアコードの担当者にもありました。コミットメールを読んで「気づく」ということはとても価値のあることです。理由や改善案がパッと思いつかなければ、なぜそう思ったのか考えるよい機会になります。考えることによって自分がなぜそう思ったのか理由が明らかになり、それをコメントを通じて相手に伝えることによって、今までそれぞれの開発者でなんとなくだった考えを共有でき、自分たちのスタイルを作っていくことができます。考えることや伝えることを避けてしまうと、このような機会を失ってしまいます。考えることや伝えることをたくさん経験すると、コミットメールを読んで気づくことが増え、それをコメントすることができるようになります。もしかしたらコメント数の増加は開発者の成長を表す指標となるかもしれません。

日々の記録について

クリアコードの日々の記録を配信するようになって、「印象に残ったコミット」が記録されることが増えましたが、まだまだ記録されない日も多いです。再度、記録を残せない原因をヒアリングして対策をするとともに、日々、記録を書くことの目的を明確にする必要があります。

ふりかえりについて

データの分析方法が確立でき、問題点の洗い出しが容易になりました。また、見つかった課題を開発チーム、クリアコードで共有し、対策を立てて次のターンで実践する流れができました。ふりかえりはこのサービスにおいて最も重要な活動だといえます。

まとめ

ミラクル・リナックスさんへのコミットへのコメントサービス導入事例を紹介しました。コミットメールを読むことで、開発チームは読みやすいコミットや自分たちのスタイルを考え、共有する機会が増えました。次のステップでは、社内の別の開発チームへ展開します。その時はクリアコードの担当者ではなく、いまサービスを受けている開発チームのメンバーが伝道師となって「みんながみんなのコードを読む文化」を伝えます。

このサービスでは、コードを読むことによってどんなよい変化が生まれるのか理解した上で、コードを読むことからはじめ、「みんながみんなのコードを読む文化」を根付かせます。読む習慣が身につくと、コードを読んだ時に気づくことが多くなります。気づいたことは、考え、話し合い、共有することによって、自分たちのスタイルとなります。これは間違いなく開発チームの財産です。そしてこの財産はよいコードを書くために活かされます。

クリアコードは、コミットへのコメントサービスを通じてみんながみんなのコードを読む文化をより多くの開発チームに伝えていきたいと考えています。コミットへのコメントサービスについて詳しく知りたい、自分たちの開発チームにも導入可能か検討したい方がいらっしゃいましたら、是非ご連絡ください。

なお、分析ツールは近日公開し、その使用方法やデータの見方はククログにて紹介する予定です。 ↩

ククログ