はじめに
「分かりやすいコードを書く」、「コードと一緒にテストも書く」等はソフトウェア開発において大切なことです。しかしそれと同じくらい大切なことして「分かりやすいコミットメッセージを書く」があります。これはあまり着目されていなく、見過ごされていることです。
今回は、コミットメッセージの分かりやすさの大切さ、そして、分かりやすくするための書き方を説明します。
コミットメッセージとその大切さ
バージョン管理システムとコミット
現在、ほとんど全てのソフトウェア開発ではSubversionやGitなどのバージョン管理システムを使っています。バージョン管理システムを使うことによるメリットというのは、ソフトウェアの変更が記録されていくことにあります。
具体的なメリットは3つあります。
-
ソフトウェアの調査がしやすくなることです。現時点でのコードと、そして変更の履歴とを組み合わせることで、それらから非常に多くの情報を得ることができます。
-
ソフトウェアを開発している人からレビューを受けられることです。自分の変更をチェックしてもらい、改善点を含めさまざまなアドバイスを貰うことができます。
-
ソフトウェアの変更を元に戻せることです。各変更がそれぞれ独立して記録されているので、時間が経過し他の追加の変更がある状態でも、過去の特定の変更だけを取り消すことができます。
このようなメリットからバージョン管理システムはソフトウェア開発に広く使われているわけです。
バージョン管理システムを前提とした上で、ソフトウェア開発を説明するならば、「バージョン管理システムに記録される変更を継続的に作成し、積み重ねていく作業」と言えます。この記録される変更というのは、具体的にはソフトウェアの変更ということになります。今回の記事では、この変更されるものを「コード」と呼ぶことにします。
以上の説明を元にして用語を整理します。バージョン管理システムでは個々に記録されていくコードの変更を「コミット」と呼びます。コミットされたコードの変更を説明している文章を「コミットメッセージ」と呼びます。
コミットの分かりやすさ
「コミット」の分かりやすさの大切さを説明する前に、まずは、「コード」の分かりやすさの大切さを説明します。
なぜコードの分かりやすさは大切なのでしょうか？理由は、コードはソフトウェア開発を通して何度も読まれるからです。多くの人に読まれる本や雑誌の文章は分かりやすいことが大切であるように、何度も読まれるコードも分かりやすいことが大切です。
では次にコミットの分かりやすさの大切さについてです。上で説明したバージョン管理システムの具体的なメリットからも分かるように、コードとコミットは常に一緒に読まれます。なので、一緒に読まれるコードと同じように、コミットも分かりやすいことが大切なのです。どんなに分かりやすいコードでもコミットが分かりにくいならば片手落ちになります。言い方を変えれば、コードと同じくらいに、コミットはソフトウェア開発の作業の重要な成果物となります。
では、コミットの分かりやすさとは何でしょうか？分かりやすいコミットとは、次の2つ条件に当てはまるものです。
-
コミットの内容が分かりやすく説明されていること
-
コミットの内容が小さくまとまっていること
今回は1つ目の条件を説明します。
コミットの内容が分かりやすいためには、具体的にはコミットメッセージが分かりやすいことが大切です。なぜならばコミットの内容を説明するために、コミットメッセージがあるからです。
ではコミットメッセージを分かりやすくするためには、どうすればいいのでしょうか？
長すぎず短すぎず
コミットメッセージは長すぎても短すぎても分かりにくくなります。長さの明確な基準はありませんが、ちょうどいい長さのコミットメッセージの目安として、コードを見なくともコミットメッセージだけから、そのコミットで行われているコードの変更がうまく想像できるかどうかです。
長すぎる場合
一度に多くの情報が含まれていると内容を把握しきれず、分かりにくくなります。コミットを詳しく説明するのは大切ですが、まずは簡単に説明し、次に詳しく説明すると分かりやすくなります。
悪い例:
repository: Ensure that the path to the .git directory ends with a forward slash when opening a repository through a working directory path
良い例:
repository: Fix bug in opening a repository in a certain case
There is a bug in opening a repository through a working
directory path.
Fix it by ensuring that the path to the .git directory ends
with a forward slash.
短すぎる場合
コミットメッセージで具体的にどんな変更をしているのかという情報が少なすぎると分かりにくくなります。実際にコードを見てから、初めて意味が理解できるコミットメッセージなどがその例です。コミットメッセージだけでコードの変更が想像できる位の情報を説明すると分かりやすくなります。
悪い例 (1):
Ate a letter
良い例 (1):
Fix a typo of a missing letter of variable name by adding it
悪い例 (2):
In-progress.
良い例 (2):
Work on new GC methods (in progress)
統一されたスタイル(文体)で書く
一般的に、統一感があると分かりやすくなります。なのでコードのスタイルが統一されていると分かりやすいのと同様に、コミットメッセージのスタイルも統一されていると分かりやすいです。
具体的には、時制を過去にするか現在にするか、ピリオド(句読点)を含めるかどうか、大文字や小文字(全角や半角)の使い方、文章形式にするか名詞形式にするかなど、様々な基準があります。
コーディングスタイルがそうであるように、コミットメッセージのスタイルは、ソフトウェア開発全体では統一されていません。だからといって各人がバラバラのスタイルで書くよりは、開発しているソフトウェア単位でスタイルを決め、統一すると分かりやすくなります。
悪い例:
- Fixed a bug
- Adds A Test
- implement nested comments
- I cleaned the parser code up.
- performance improvement
良い例:
- Fix a bug
- Add a test
- Implement nested comments
- Clean the parser code up
- Improve performance
ちなみに、今回の記事では次のスタイルを採用しています(Gitスタイル)。
- 言語は英語にする
- 一文の場合にはピリオドを付けない
- 主語は省き時制は現在の文章形式にする
- 文頭の英単語を大文字にする
英語で書く
主要なプログラミング言語は、英語が前提となっており、コードも同様です。上で説明した統一感のためにも、コミットも英語で書くと分かりやすいです。
ソフトウェア開発では英語の読み書きが必要となります。日頃から英語で書くことで、英語に慣れることができるというメリットがあります。
また、英語は世界でもっとも広く使われている言語であり、多くの人が読めます。つまり、多くの人が開発に参加できるフリーソフトウェア開発の場合は、英語を使うことはことさら大切になります。
悪い例:
新しいデータ型に対応
良い例:
Support new data types
まとめ
今回はコミットメッセージについて、分かりやすいことは大切であり、分かりやすくするための書き方を説明しました。
具体的な書き方として、長すぎず短すぎず、統一されたスタイルで、英語のコミットメッセージを書けば分かりやすくなるということを説明しました。
