try to write a better commit message

1

Try to write a better commit

message

乙女とデブに体重は聞いちゃダメ

• 松田淳平• 東工大佐伯研 M2• Java, Kotlin, Ruby, シェル芸 (Bash&MacOSX)• twitter:@fat_daruuuuma, github:jmatsu

3

今日の内容• 良いコミットメッセージを書くために気をつけよう，みたいなことの一部• 個人の見解であり，所属する団体等を代表するものではありません云々

4

近年主流の開発方法• バージョン管理システム (VCS) を用いる

• 近年は Git が主流• 複数の開発者が VCS を通して並列に開発

• そこらへんは VCS がよしなにしてくれる• VCS が管理する変更 ( コミット ) を開発に利用

• E.g. バグ発生原因の特定等

5

より良い開発のために• コミットの内容に規則を設ける

• A commit should be atomic/logical change• コミット 1 つ 1 つの方向性を明確化する

• Don’t mix whitespace changes with the others• 差分の意味を強調し，なおかつ競合の可能性を下げる

• コミットメッセージに規則を設ける• Write the intention which makes a change

• 関連チケットや差分内容の根本を明文化する

• Etc.

6





• 関連チケットや差分内容を明確化する

• Etc.

研究対象(Git)

7





• 関連チケットや差分内容を明確化する

• Etc.

今日はこっち(Git)

8

良い / 悪いを制御する規則• 残念ながら明確なものはない

• 主観や客観に委ねられる• 譲歩 ( 努力目標 )

• 明らかに悪いものは避ける• 校長先生の話みたいにしない

• 同じ話の繰り返し• いつまで経っても本題に入らない

9





10

悪いコミット例 - 最悪

11

悪いコミット例 - 最悪

• どの口がほざいてんだ

12





13

悪いコミット例 - 校長先生• 同じことを何度も・・・

14

そもそもコミットメッセージとは• 自然言語で書かれ，• コミットの内容 ( 差分 ) を補足・強調し，• 開発者間で共有され，• VCS の管理対象となるもの

15

メッセージの重要な役割• 「コミットの説明」

• 何に対して，なぜ，どのような変更をしたからこういう結果が得られた• 「他開発者 or 未来の自分へのメッセージ」

• E.g. このコミットは他とは混ぜないで欲しい• 「ドキュメント」

• 正確なメッセージは仕様書の変更と同期している• 「開発段階の示唆」

• pre/post - factoring ，新機能追加の準備等

16

ボトルネック• 自然言語の自由度の高さ

• 表現力や表現される粒度が個々人に依存する• 表現すべきことが多い

• ボリュームがあると読む気も失せてしまう• 当然書く気も失せてしまう

17

ボトルネック• 自然言語の自由度の高さ

• 表現力や表現される粒度が個々人に依存する• 表現すべきことが多い

• ボリュームがあると読む気も失せてしまう• 当然書く気も失せてしまう

Git が扱う基本フォーマットに加え，簡素なフォーマットを定義する

18

基本フォーマット• 1 行目 : “Subject”

• コミット内容の概略や主題• 半角で 50 文字以下 ( ログの見やすさのため )

• 2 行目 : 空行• パースに使われるので重要

• N 行目 : ”Body” (N ≧ 3)• コミット内容の詳細

19

基本フォーマット像と例#1 [Subject]#2 #3... [Body]

E.g.#1 Fixed a typo#2 #3 In README.md, #4 modified “encding” to “encoding”

20



1 つの Typo を直した

21



README.md の中，encding -> encoding

22

Subject と Body• Subject で Why や How まで説明するのはくどい

• つまんない話にありがち第二弾• ず〜〜〜〜〜〜〜〜っと原因を言う• 結論がいつまで経ってもこない• 特に日本語にありがち

• Subject+Body で物語を作る• Subject で What を表現• Body で Why, How を表現

23

Subject• What を的確に記述• 詳細を見る必要の有無がひと目で分かるべき

• 他の部分にどれだけの影響度があるのか• 挙動は変更されるのか• どんな目的を基礎としているのか

• 複文は避けられるに越したことはない• 単文ごとにコミットを再構成できる可能性

• プルリクエストのタイトルに成り得る

24

書くべきこと – Subject -• フォーマット ( 半角で 50 文字以下 )

• Type Targets [and others]• Type

• コミットの種別を表現する• この単語で「何をしたのか」が一目で分かるべき• 英語だと過去形なことが多い

• Targets (and others)• Type の対象や操作種別等の補足を行う

• 言語は英語か混合 ( 英 + 日 ) が望ましい

25






26

Types of a commit• 基本 : fix : バグ修正 ,

add : ファイルの追加 , modify : 修正 (not fix), change : 仕様変更 , refactor : リファクタリング , remove : ファイルの削除 , delete : コメント等の削除， reformat : コード整形

• 任意 : update : 依存等の更新 , revert : 変更の取り消し ,

simplify : 単純化

27

Types of a commit• 基本 : fix : バグ修正 ,

add : ファイルの追加 , modify : 修正 (not fix), change : 仕様変更 , refactor : リファクタリング , remove : ファイルの削除 , delete : コメント等の削除， reformat : コード整形

• 任意 : update : 依存等の更新 , revert : 変更の取り消し ,

simplify : 単純化

28






29

Targets [and others]• Type の対象や補足情報の追加

• Target• Type と組み合わせれば「何に何をしたか」が分かる

• And others• 変更を行う上での行動原理・理由の”概要”を表現する

• E.g. • チケット No.9999 に関連． A から B へページ遷移するときに渡すべきパラメータに無駄があったのでコントローラー C を修正．

• Target : コントローラー C• And others : ムダの排除

30






31

使用言語• 英語 (Best) ，混合 (Better) ，日本語 (Bad)• 日本語は論法の順序がよろしくない

• 英語 : 結論 → 原因 • 日本語 : 原因 → 結論

• 混合は便利 ( 日本人に限れば )• Type は前述の規定文字群から選べばいい

• 英語が下手でも大丈夫• 詳細はネイティブの言語の方が説明しやすい

• ※ ルー語じゃないよ

32

Body• コミットの詳細を記述

• フォーマットは特になし• コードレビューの補助となる

• 「メッセージとコミットの内容に差があること」は欠点ではなく，重要な情報のひとつになる• 可能なら得意言語で書かれるべき• 書く必要がないことと書けないことは違う

• 書けない場合は Why の部分が欠けたまま編集をしてしまった可能性が大きい

33

書くべきこと – Body -• コミットに対する問への詳細な答えを記述する

• なぜその変更が必要なのか• どうやってその問題を解決したか• どんな影響があるか• どのチケットに関連し，解決するのか etc.

• 上記は最低限• 当然書けば書くほど情報を足すことができる• 重要な事項を後ろの方に追いやらないのであれば，気の済むまで書けばいい

• ファーストセンテンスが主張になるようにする

34

Body の How• Subject の「何に，何をしたのか」と差別化

• Subject は変更の種別を記述• Body は状況 + 方法論を記述

• Context を保持する目的がある• 前提条件• 方針 ( 理由 + 方法 )• 副作用の有無

35

メッセージの質を低下させる要素• コミットのサイズ

• 大きすぎる変更はその分だけ説明が多くなる• コミットとしてもあまりよろしくない

• 語句の表記揺れ• 特に日本語は表記揺れの可能性が高い

• E.g. 修正や変更，直す• 日本語ではひらがな /カタカナ /漢字の使い分けが存在

• Grep時の障害になったり，意味が変わるケースも• 感情，疲労

• 非常に雑になる

36

まとめ。• Subject + Body で物語を作る

• 素晴らしいメッセージは利用価値が高くなる• Subject で What を表現

• 目を引くように，簡潔に「何に何をしたのか」• Format : Type Targets [and others]

• Body で Why, How を表現• Subject の背景や修正方法を細かに記述する• 「主張」はファーストセンテンスで• Format : 特になし

37

おまけ。• git config --global core.editor emacsはちゃんとしましょうね！！！• (Vim でも MacVim でも何でもいいけど )

• git commit –m “ ほげっ” だと Body 書きづらい• git commit でエディタを起てて書きましょう

try to write a better commit message

Engineering