mmyoji's diary

プログラミングとか日々のどうでもいいこととか

イカしたエンジニアになるためのイカしたコミットメッセージ

今お仕事させていただいている会社で、以前 【コミッター登壇】プログラマーのための「Rubyの世界」 - connpass で登壇された @idesaku さんとも一緒に働かせていただいてて、今日ありがたいことにマンツーマン(死語?)でgitのコミットメッセージについて講義をしていただいて、それがめちゃめちゃよかったのでブログに残しておこうと思います?

commitメッセージに関する記事などを以前色んな人が書いてるのを見た気がしますが、個人的な経験として今日得られたのがインパクト強かったので、多少被ったりはしているかもしれませんが、そこらへんはスルーしてくださいmm

経緯

  • 僕のPull Requestに付くコメントが毎回コード自体というよりは commit に関することばかり
    • 「このコミットメッセージは微妙では?」
    • 「この変更はブランチ名に合ってないんじゃないですかね?」
    • 「この内容は今回のPRに含むべきじゃない。もしくはコミットを分けるべきだ」
    • など

(実際はもっと柔らかい口調ですよ!)

なぜ??

  • idesakuさんは基本的にgitで全部完結させる人だった => git log で出てくる情報をソースにして仕事をされてる(それが普通?)
  • 僕はどちらかというとgithubesa, Qiita:Teamなどに情報がないか調べることが多い(単にgitコマンドあんまり使いこなせてないだけとも言える)

idesakuさんの思考プロセス

  • 変なコードを発見する
  • 「なんでこんな書き方した??」
  • git log -S"search_words" などで調べる
  • commitメッセージは add "git:" options to the gem "foo"
  • 「いやいや追加したのは git log -p すれば分かるから」
  • その修正を加えることで何が変わる/良くなるのか や、 変更することに至った経緯 が知りたい!!

原則

add, fix, remove などの単語は極力避ける

  • メッセージを考えることを放棄することにつながりやすい

目的語に 形容詞 をつけるようにする

  • 仮に上記の動詞を使ったとしても形容詞で意図を伝えることを補える
  • remove users/detail view よりは remove **unused** users/detail view
    • =>「使われてない」から消したのか
  • fix xxx method よりは fix **dangerous** xxx method from the security point of view
    • =>「セキュリティ面で危険」だったから直したのか

チームである程度合意のあるemojiを使う

読み手の気持ちを考える

  • 未来の自分がそのメッセージを読むことでコードの意図を汲めるか?

gitしかない世界を想定する

  • githubesa, Qiita:Teamなどにある補足情報を前提に考えない場合でも、コードの変更をした意図が正確に伝わるか?
  • 僕みたいにプログラミング始めたタイミングで既にgithubなどのツールを使ってた人は特に。
    • 「Pull Requestのdescriptionに詳細書くから、コミットメッセージとか大体でいいじゃん??」って感覚があった。
    • ただ必ずしも事細かに書けばいいってものでもないと思う、とidesakuさんはおっしゃってて、それはその通りだと思った。

個人的に更に気をつけたいこと

git commit -m 使わない

  • ワンライナーで書いてしまうので, 考える時間を省こうとしてしまう
  • 3行目以降を書かないことが前提になってしまう

オシャレでイカしたコミットメッセージを書くことをモチベーションにする

  • 「コミットメッセージがダサいとエンジニアとして恥ずかしい」、という価値観を持つ

どんなに長く考えてもせいぜい5分程度だからちゃんと考えろ

  • 未来の自分・プロジェクト参加者の時間を節約できることを考えればお釣りが来るレベルなので、そこにしっかりとコストをかける

合わせて読みたさ( ˘ω˘)

@ken_c_lo さんの記事ですがtwitterでイカのような真実(!)を教えていただきました( ˘ω˘)

おわりに

我々エンジニア・プログラマはどんな文字情報にも気を抜くことがゆるされないのだなぁ〜としみじみ( ˘ω˘)

※本記事中の英語とか日本語がおかしいのは目をつぶってください?