こんにちは @color_box です。 チームとしてサービス開発に関わっていると、普段の開発の中で、自分の書いたものではないコードや、数年前に作成されたコードを修正する機会が多くあります。
そのような時に修正しやすいと感じたコミットやそれに関わる有用な心がけを紹介しようと思います。
TL;DR
開発しやすい環境のために下記2つを行う
- コミットメッセージ内に関連するチケットへのリンクを記載する
- 1つの修正は1コミットの粒度にして、コミットにテストを含める
前提
特定のコードを修正する時、その修正によって別の不具合が出ないようしなくてはいけません。 そのため、修正対象となるそのコードがなぜそうなっているかを把握する必要があります。 その時参照すべきものとして、コードそのものに加え、その機能の仕様書やテストなどがあります。
しかし、コードからそのような資料を探りづらいと、仕様の把握に時間がかかります。 チケットシステム内を検索したり、チャットの過去ログを漁ったりする必要が出てきます。 そして、そのような調査は時間がかかります。
それらの資料をコードから探せるようになっていると資料検索に使う時間が減ります。 無駄な時間が減り、開発に集中できるため、開発しやすくなります。
そのような開発をしやすい環境のために私がコミット時に心がけている事を書いていきます。
コミットメッセージにチケットへのリンクを書く
このルールはコード(コミット)から、関連資料に到達しやすくなるためのルールです。
git blameで、コードからコミットを辿れます。 その時、コミットメッセージにチケットへのリンクがあれば、機能修正or機能追加時に使用されたチケットを参照しやすいです。
チケット上では仕様変更についての議論が残っています。それらからコードのもととなった仕様の変遷を把握できます。 コードを修正する上で、この情報があると適切な修正や提案を行うことが可能です。
もちろん、コミットメッセージにそういった情報があるのが一番良いのですが、コードの細かい箇所となると、そういった情報がコミットメッセージに載っていないこともあります。 そういう時はチケットまでさかのぼって見に行く必要があります。
ひとつの変更理由は、一つのコミットで
このルールは1つのコミットが特定の1つの修正と紐付いていることを保証するためのルールです。 1つの修正とそれに関連するテストが1つのコミットにまとまっていると、どのテストがどの修正と紐付いているかが明確となります。
機能について理解を深める時、コードを読むのに加えてE2Eテストを読みます。 このルールが守られていると、読むべきテストをコードから探しやすくなります。
テストを仕様理解のための資料として捉え、コードからテストを補足しやすくするためのルールです。
この記事に書いたルールは、下記例外を除いて多くのプロジェクトで機能するルールだと思われます。
- 仕様に関する議論が対面口頭で行われ、それに関する記録が殆ど残らないようなプロジェクト
- 仮説検証が目的で、生存期間が短いことが確定している使い捨てプロジェクト
私がプロジェクトで開発しやすい環境にするために心がけているルールを紹介させていただきました。 どなたかのお役に立てば幸いです。
