適当なLT

1. Try to write
a better commit message
1

2. 乙女とデブに体重は聞いちゃダメ
• 松田 淳平
• 東工大 佐伯研M2
• Java, Kotlin, Ruby, シェル芸(Bash&MacOSX)
• twitter:@fat_daruuuuma, github:jmatsu

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

4. 近年主流の開発方法
• バージョン管理システム(VCS)を用いる
• 近年はGitが主流
• 複数の開発者がVCSを通して並列に開発
• そこらへんはVCSがよしなにしてくれる
• VCSが管理する変更(コミット)を開発に利用
• E.g. バグ発生原因の特定 等
4

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. 5

6. より良い開発のために
• コミットの内容に規則を設ける
• 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
研究対象
(Git)

7. より良い開発のために
• コミットの内容に規則を設ける
• 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. 7
今日はこっ
ち
(Git)

8. 良い/悪いを制御する規則
• 残念ながら明確なものはない
• 主観や客観に委ねられる
• 譲歩(努力目標)
• 明らかに悪いものは避ける
• 校長先生の話みたいにしない
• 同じ話の繰り返し
• いつまで経っても本題に入らない
8

9. 良い/悪いを制御する規則
• 残念ながら明確なものはない
• 主観や客観に委ねられる
• 譲歩(努力目標)
• 明らかに悪いものは避ける
• 校長先生の話みたいにしない
• 同じ話の繰り返し
• いつまで経っても本題に入らない
9

10. 悪いコミット例 - 最悪
10

11. 悪いコミット例 - 最悪
• どの口がほざいてんだ
11

12. 良い/悪いを制御する規則
• 残念ながら明確なものはない
• 主観や客観に委ねられる
• 譲歩(努力目標)
• 明らかに悪いものは避ける
• 校長先生の話みたいにしない
• 同じ話の繰り返し
• いつまで経っても本題に入らない
12

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

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

15. メッセージの重要な役割
• 「コミットの説明」
• 何に対して，なぜ，どのような変更をしたからこうい
う結果が得られた
• 「他開発者or未来の自分へのメッセージ」
• E.g. このコミットは他とは混ぜないで欲しい
• 「ドキュメント」
• 正確なメッセージは仕様書の変更と同期している
• 「開発段階の示唆」
• pre/post - factoring，新機能追加の準備 等
15

16. ボトルネック
• 自然言語の自由度の高さ
• 表現力や表現される粒度が個々人に依存する
• 表現すべきことが多い
• ボリュームがあると読む気も失せてしまう
• 当然書く気も失せてしまう
16

17. ボトルネック
• 自然言語の自由度の高さ
• 表現力や表現される粒度が個々人に依存する
• 表現すべきことが多い
• ボリュームがあると読む気も失せてしまう
• 当然書く気も失せてしまう
Gitが扱う基本フォーマットに加え，
簡素なフォーマットを定義する
17

18. 基本フォーマット
• 1行目 : “Subject”
• コミット内容の概略や主題
• 半角で50文字以下 (ログの見やすさのため)
• 2行目 : 空行
• パースに使われるので重要
• N行目 : ”Body” (N ≧ 3)
• コミット内容の詳細
18

19. 基本フォーマット像と例
#1 [Subject]
#2
#3... [Body]
E.g.
#1 Fixed a typo
#2
#3 In README.md,
#4 modified “encding” to “encoding”
19

20. 基本フォーマット像と例
#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. 基本フォーマット像と例
#1 [Subject]
#2
#3... [Body]
E.g.
#1 Fixed a typo
#2
#3 In README.md,
#4 modified “encding” to “encoding”
21
README.mdの中，
encding -> encoding

22. SubjectとBody
• SubjectでWhyやHowまで説明するのはくどい
• つまんない話にありがち第二弾
• ず〜〜〜〜〜〜〜〜っと原因を言う
• 結論がいつまで経ってもこない
• 特に日本語にありがち
• Subject+Bodyで物語を作る
• SubjectでWhatを表現
• BodyでWhy, Howを表現
22

23. Subject
• Whatを的確に記述
• 詳細を見る必要の有無がひと目で分かるべき
• 他の部分にどれだけの影響度があるのか
• 挙動は変更されるのか
• どんな目的を基礎としているのか
• 複文は避けられるに越したことはない
• 単文ごとにコミットを再構成できる可能性
• プルリクエストのタイトルに成り得る
23

24. 書くべきこと – Subject -
• フォーマット (半角で50文字以下)
• Type Targets [and others]
• Type
• コミットの種別を表現する
• この単語で「何をしたのか」が一目で分かるべき
• 英語だと過去形なことが多い
• Targets (and others)
• Typeの対象や操作種別等の補足を行う
• 言語は英語か混合(英+日)が望ましい
24

25. 書くべきこと – 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 : 単純化 26

27. Types of a commit
• 基本 : fix : バグ修正,
add : ファイルの追加,
modify : 修正(not fix),
change : 仕様変更,
refactor : リファクタリング,
remove : ファイルの削除,
delete : コメント等の削除，
reformat : コード整形
• 任意 : update : 依存等の更新,
revert : 変更の取り消し,
simplify : 単純化 27

28. 書くべきこと – Subject -
• フォーマット (半角で50文字以下)
• Type Targets [and others]
• Type
• コミットの種別を表現する
• この単語で「何をしたのか」が一目で分かるべき
• 英語だと過去形なことが多い
• Targets (and others)
• Typeの対象や操作種別等の補足を行う
• 言語は英語か混合(英+日)が望ましい
28

29. Targets [and others]
• Typeの対象や補足情報の追加
• Target
• Typeと組み合わせれば「何に何をしたか」が分かる
• And others
• 変更を行う上での行動原理・理由の”概要”を表現する
• E.g.
• チケットNo.9999に関連．AからBへページ遷移すると
きに渡すべきパラメータに無駄があったのでコント
ローラーCを修正．
• Target : コントローラーC
• And others : ムダの排除
29

30. 書くべきこと – Subject -
• フォーマット (半角で50文字以下)
• Type Targets [and others]
• Type
• コミットの種別を表現する
• この単語で「何をしたのか」が一目で分かるべき
• 英語だと過去形なことが多い
• Targets (and others)
• Typeの対象や操作種別等の補足を行う
• 言語は英語か混合(英+日)が望ましい
30

31. 使用言語
• 英語(Best)，混合(Better)，日本語(Bad)
• 日本語は論法の順序がよろしくない
• 英語 : 結論 → 原因
• 日本語 : 原因 → 結論
• 混合は便利(日本人に限れば)
• Typeは前述の規定文字群から選べばいい
• 英語が下手でも大丈夫
• 詳細はネイティブの言語の方が説明しやすい
• ※ ルー語じゃないよ
31

32. Body
• コミットの詳細を記述
• フォーマットは特になし
• コードレビューの補助となる
• 「メッセージとコミットの内容に差があること」は
欠点ではなく，重要な情報のひとつになる
• 可能なら得意言語で書かれるべき
• 書く必要がないことと書けないことは違う
• 書けない場合はWhyの部分が欠けたまま編集をしてし
まった可能性が大きい
32

33. 書くべきこと – Body -
• コミットに対する問への詳細な答えを記述する
• なぜその変更が必要なのか
• どうやってその問題を解決したか
• どんな影響があるか
• どのチケットに関連し，解決するのか etc.
• 上記は最低限
• 当然書けば書くほど情報を足すことができる
• 重要な事項を後ろの方に追いやらないのであれば，気
の済むまで書けばいい
• ファーストセンテンスが主張になるようにする
33

34. BodyのHow
• Subjectの「何に，何をしたのか」と差別化
• Subjectは変更の種別を記述
• Bodyは状況 + 方法論を記述
• Contextを保持する目的がある
• 前提条件
• 方針 (理由 + 方法)
• 副作用の有無
34

35. メッセージの質を低下させる要素
• コミットのサイズ
• 大きすぎる変更はその分だけ説明が多くなる
• コミットとしてもあまりよろしくない
• 語句の表記揺れ
• 特に日本語は表記揺れの可能性が高い
• E.g. 修正や変更，直す
• 日本語ではひらがな/カタカナ/漢字の使い分けが存在
• Grep時の障害になったり，意味が変わるケースも
• 感情，疲労
• 非常に雑になる
35

36. まとめ。
• Subject + Bodyで物語を作る
• 素晴らしいメッセージは利用価値が高くなる
• SubjectでWhatを表現
• 目を引くように，簡潔に「何に何をしたのか」
• Format : Type Targets [and others]
• BodyでWhy, Howを表現
• Subjectの背景や修正方法を細かに記述する
• 「主張」はファーストセンテンスで
• Format : 特になし
36

37. おまけ。
• git config --global core.editor emacs
はちゃんとしましょうね！！！
• (VimでもMacVimでも何でもいいけど)
• git commit –m “ほげっ” だとBody書きづらい
• git commitでエディタを起てて書きましょう
37