コミットメッセージの書き方コミットメッセージの書き方2012-02-21はじめに「分かりやすいコードを書く」、「コードと一緒にテストも書く」等はソフトウェア開発において大切なことです。それと同じくらい大切なことして「分かりやすいコミットメッセージを書く」があります。これはあまり着目されていなく、見過ごされていることです。今回は、コミットメッセージの分かりやすさの大切さ、そして、分かりやすくするための書き方を説明します。コミットメッセージとその大切さバージョン管理システムとコミット現在、ほとんど全てのソフトウェア開発ではSubversionやGitなどのバージョン管理システムを使っています。バージョン管理システムを使うことによるメリットというのは、ソフトウェアの変更が記録されていくことにあります。具体的なメリットは3つあります。ソフトウェアの調査がしやすくなることです。現時点でのコードと、そして変更の履歴とを組み合わせることで、それらから非常に多くの情報を得ることができます。ソフトウェアを開発している人からレビューを受けられることです。自分の変更をチェックしてもらい、改善点を含めさまざまなアドバイスを貰うことができます。ソフトウェアの変更を元に戻せることです。各変更がそれぞれ独立して記録されているので、時間が経過し他の追加の変更がある状態でも、過去の特定の変更だけを取り消すことができます。このようなメリットからバージョン管理システムはソフトウェア開発に広く使われているわけです。バージョン管理システムを前提とした上で、ソフトウェア開発を説明するならば、「バージョン管理システムに記録される変更を継続的に作成し、積み重ねていく作業」と言えます。この記録される変更というのは、具体的にはソフトウェアの変更ということになります。今回の記事では、この変更されるものを「コード」と呼ぶことにします。以上の説明を元にして用語を整理します。バージョン管理システムでは個々に記録されていくコードの変更を「コミット」と呼びます。コミットされたコードの変更を説明している文章を「コミットメッセージ」と呼びます。コミットの分かりやすさ「コミット」の分かりやすさの大切さを説明する前に、まずは、「コード」の分かりやすさの大切さを説明します。コードの分かりやすさは大切なのでしょうか?理由は、コードはソフトウェア開発を通して何度も読まれるからです。多くの人に読まれる本や雑誌の文章は分かりやすいことが大切であるように、何度も読まれるコードも分かりやすいことが大切です。次にコミットの分かりやすさの大切さについてです。上で説明したバージョン管理システムの具体的なメリットからも分かるように、コードとコミットは常に一緒に読まれます。一緒に読まれるコードと同じように、コミットも分かりやすいことが大切なのです。どんなに分かりやすいコードでもコミットが分かりにくいならば片手落ちになります。言い方を変えれば、コードと同じくらいに、コミットはソフトウェア開発の作業の重要な成果物となります。コミットの分かりやすさとは何でしょうか?分かりやすいコミットとは、次の2つ条件に当てはまるものです。コミットの内容が分かりやすく説明されていることコミットの内容が小さくまとまっていること今回は1つ目の条件を説明します。コミットの内容が分かりやすいためには、具体的にはコミットメッセージが分かりやすいことが大切です。コミットの内容を説明するために、コミットメッセージがあるからです。コミットメッセージを分かりやすくするためには、どうすればいいのでしょうか?長すぎず短すぎずコミットメッセージは長すぎても短すぎても分かりにくくなります。長さの明確な基準はありませんが、ちょうどいい長さのコミットメッセージの目安として、コードを見なくともコミットメッセージだけから、そのコミットで行われているコードの変更がうまく想像できるかどうかです。一度に多くの情報が含まれていると内容を把握しきれず、分かりにくくなります。コミットを詳しく説明するのは大切ですが、まずは簡単に説明し、次に詳しく説明すると分かりやすくなります。slash.短すぎる場合コミットメッセージで具体的にどんな変更をしているのかという情報が少なすぎると分かりにくくなります。実際にコードを見てから、初めて意味が理解できるコミットメッセージなどがその例です。コミットメッセージだけでコードの変更が想像できる位の情報を説明すると分かりやすくなります。progress)統一されたスタイル(文体)で書く一般的に、統一感があると分かりやすくなります。コードのスタイルが統一されていると分かりやすいのと同様に、コミットメッセージのスタイルも統一されていると分かりやすいです。具体的には、時制を過去にするか現在にするか、ピリオド(句読点)を含めるかどうか、大文字や小文字(全角や半角)の使い方、文章形式にするか名詞形式にするかなど、様々な基準があります。コーディングスタイルがそうであるように、コミットメッセージのスタイルは、ソフトウェア開発全体では統一されていません。いって各人がバラバラのスタイルで書くよりは、開発しているソフトウェア単位でスタイルを決め、統一すると分かりやすくなります。performanceちなみに、今回の記事では次のスタイルを採用しています(Gitスタイル)。言語は英語にする一文の場合にはピリオドを付けない主語は省き時制は現在の文章形式にする文頭の英単語を大文字にする英語で書く主要なプログラミング言語は、英語が前提となっており、コードも同様です。上で説明した統一感のためにも、コミットも英語で書くと分かりやすいです。ソフトウェア開発では英語の読み書きが必要となります。日頃から英語で書くことで、英語に慣れることができるというメリットがあります。英語は世界でもっとも広く使われている言語であり、多くの人が読めます。多くの人が開発に参加できるフリーソフトウェア開発の場合は、英語を使うことはことさら大切になります。typesまとめ今回はコミットメッセージについて、分かりやすいことは大切であり、分かりやすくするための書き方を説明しました。具体的な書き方として、長すぎず短すぎず、統一されたスタイルで、英語のコミットメッセージを書けば分かりやすくなるということを説明しました。フリーソフトウェア開発での開発の仕方をベースに、成果や知識を公開し共有しながら業務に携われます。クリアコードのYouTubeチャンネルです。メンバーの登壇動画や、開発プロダクトに関する動画を公開しています。4.0とGFDLのデュアルライセンスで自由に利用できます。クリアコードはプログラミングが楽しいソフトウェア開発者を1名募集しています。クリアコードは「クリアコードをいい感じにする人」を1名募集しています。クリアコードはフリーソフトウェア開発で培った技術力を提供しています。Thunderbird)とRubyとGroonga(全文検索)に関連した開発を得意としています。株式会社クリアコード。