Try to write a better commit message 1
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
より良い開発のために• コミットの内容に規則を設ける
• 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.
研究対象(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.
今日はこっち(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 [Subject]#2 #3... [Body]
E.g.#1 Fixed a typo#2 #3 In README.md, #4 modified “encding” to “encoding”
1 つの Typo を直した
21
基本フォーマット像と例#1 [Subject]#2 #3... [Body]
E.g.#1 Fixed a typo#2 #3 In README.md, #4 modified “encding” to “encoding”
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
書くべきこと – Subject -• フォーマット ( 半角で 50 文字以下 )
• Type Targets [and others]• Type
• コミットの種別を表現する• この単語で「何をしたのか」が一目で分かるべき• 英語だと過去形なことが多い
• Targets (and others)• Type の対象や操作種別等の補足を行う
• 言語は英語か混合 ( 英 + 日 ) が望ましい
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
書くべきこと – Subject -• フォーマット ( 半角で 50 文字以下 )
• Type Targets [and others]• Type
• コミットの種別を表現する• この単語で「何をしたのか」が一目で分かるべき• 英語だと過去形なことが多い
• Targets (and others)• Type の対象や操作種別等の補足を行う
• 言語は英語か混合 ( 英 + 日 ) が望ましい
29
Targets [and others]• Type の対象や補足情報の追加
• Target• Type と組み合わせれば「何に何をしたか」が分かる
• And others• 変更を行う上での行動原理・理由の”概要”を表現する
• E.g. • チケット No.9999 に関連. A から B へページ遷移するときに渡すべきパラメータに無駄があったのでコントローラー C を修正.
• Target : コントローラー C• And others : ムダの排除
30
書くべきこと – Subject -• フォーマット ( 半角で 50 文字以下 )
• Type Targets [and others]• Type
• コミットの種別を表現する• この単語で「何をしたのか」が一目で分かるべき• 英語だと過去形なことが多い
• Targets (and others)• Type の対象や操作種別等の補足を行う
• 言語は英語か混合 ( 英 + 日 ) が望ましい
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 でエディタを起てて書きましょう