「Doxygen」を含む日記 RSS

はてなキーワード: Doxygenとは

2016-07-25

gitにおけるコミットログ/メッセージ例文集100

私はコミットログの書き方に悩む英語の苦手な人間である。実際、似たような人は世の中に結構いるようで、頻出単語を集計したりまとめたものは既にあって役に立つのだけれど、これらはあくま単語の話であり、具体的な文を構成する過程でやっぱり困る部分がかなりあった。

要するに、どういう時にどういう文が使われているのか、ということを示した例文集が欲しいのであるググると他にも「例文集があればいいのに」みたいな声はあるくせして、しかし誰も作ろうとしない。何なんだお前ら。それじゃ私が楽できないじゃないか

仕方なく自分でまとめたので、増田に垂れ流しておく。

はじめに

ここで挙げているコミットログは全て実際のコミットログから転載である。当然ながら各コミットログ著作権はそれぞれの書き手にある。いずれも各英文でググれば出てくるし、フェアユース範囲なら許してくれるだろうと考え名前プロジェクト名は割愛したが、ここにお詫びと感謝を述べておきたい。

抽出条件だが、参考にできそうなコミットログを多く含んでいそうなリポジトリGitHubSTARの多い方からざっと目で見て適当に選び、それぞれ最新コミットから5000件抽出した(あわせて前処理として、コミットログ冒頭のタグ情報は消去した)。

結果として対象としたリポジトリは以下の通り。

atomのみ5400件抽出していたため、計25400件のコミットログベースである。このうち、以下の条件に合致するものは参考例にすべきでないとして一律排除した。

こうして残った8540件を眺めながら、適当に切り出したのがこの用例集である個人的に「うーんこの」と思った表現も、散見される場合は載せた。

ということで、以下用例を羅列していく。

用例集

オプションフラグメニューを追加した
ファイルを追加した
メソッド機能を追加した
実装を別のものへ切り替えた
  • Use args.resourcePath instead of args.devResourcePath
  • Use arrays instead of while loops
  • Use auto instead of repeating explicit class names
  • Use weak pointer instead of manual bookkeeping
  • Change all uses of 'CInt' to 'Int32' in the SDK overlay
  • Change Integer#year to return a Fixnum instead of a Float to improve consistency
新しく何かに対応した/機能上の制約を取り払った
何かを使うようにした
より好ましい実装に改良した
何かを出来ない/しないようにした
  • Don't bail reading a metadata instance if swift_isaMask isn't available
  • Don't exit until the parent asks for an instance
  • Don't include Parent pointer in Nominal/BoundGeneric TypeRef uniquing
  • Don't use MatchesExtension for matching filters
  • Don't use ES6 class for AutoUpdater windows class
  • Don't use MatchesExtension for matching filters
  • Avoid `distinct` if a subquery has already materialized
  • Avoid infinite recursion when bad values are passed to tz aware fields
オブジェクトの内容や挙動確認やすくした
Assertを追加した
不要コードを除去した
コードを移動した
名前修正した
さなバグタイポ修正した, 警告を潰した
バグや好ましくない挙動修正した
テストコメントドキュメントを追加した
テストを削除した
テストコメント修正した
ドキュメント修正した

表現傾向とまとめ

以上の用例をふまえ、今回の参考ログ8540件から先頭の単語を出現回数で並べると次のようになった。

Add1149
Fix1014
Update584
Remove566
Use382
Don't260
Make228
Move178
Change103
Rename85
Improve76
Avoid68
Allow65
Implement60
Handle58

コミットログの基本形はもちろん動詞 + 名詞である名詞固有名詞複数形、不可算名詞が多いが、単数形場合冠詞は a が使われるか、あるいは省略される。the はまず使われない。

何かを追加した、という表現では非常に広く Add が使われる。メソッドからテストドキュメントに至るまで大概これでまかなえる。

一方、何かを修正した、という表現では広く Fix が使われる。「何か」は typocrash といった単語からメソッド名まで幅広い名詞を取るが、動名詞はあまり取らないのと、that節は取らないのでその点は注意が必要である

Fix は「何かが正しく動くようにした」ことを示し、正しい動作内容が何かを説明しない。そこで正しい動作内容に言及したい場合Make sure が使われる(こちらはthat節が取れる)。ただし Fix よりもニュアンス的に重い表現と思われ、Fix を使わず Make sure ばかり使うのはちょっとキモいのではないかと思う(Ensure はさらに重い表現っぽい)。

また、Fixtypo 以外でのドキュメント修正に対して使われることは稀である。対して Update はドキュメントコメントテストに使われ、本体コード修正に対しては使われない。本体コード修正にあわせてテスト更新したなら Update が使われる。ただ、テスト機構それ自体バグ修正したなら Fix である

無駄な何かを単純に除去したなら Remove を使う。これまでのもの(A)からのもの(B)に切り替えたのであれば Use B instead of A か Change A to B が使われる。新たに何かを利用するようにしたのであれば Use を、利用を取りやめた場合Don't use を使うことが多い。

何かをしないようにしたなら Don't を、内部実装効率化なら Make A + 比較級/形容詞Improve が使われる。

中身の変更を伴わない単なる名前の変更なら Rename A to B、コード機能論理上の場所を移動させたなら Move A to B である

この辺はリファクタリングと呼ばれる行為と思うが、Refactor というぼんやりした動詞はあまり使われず、このように変更内容の種類に応じて動詞が使い分けられている。

余談

コミットログにはWhyを書くべきだ、というのを何かで見かけたので because とか since を使ったログがどの程度あるかを調べたが、8540件のうち22件だった。基本的に短く、シンプルに、一目で意味が取れるログが好まれる傾向がある。例えば get rid of とか2件しか使われておらず、圧倒的に remove である

一方で、シンプル単語だけど開始単語としては使われないものもある。例えば次のような単語である。Expand(9)、Extend(8)、Print(5)、Optimize(5)、Publish(4)、Append(4)、Modify(3)、Manage(2)、Revise(2)、Dump(2)、Insert(2)、Migrate(2)、Enhance(1)、Edit(1) 。いずれもカッコ内は8540件に対する冒頭での登場回数である。結局、より一般的平易な単語で表せたり、Refactor同様に抽象度が高すぎると使われないのだろう。

おわりに

8000件もログを見たおかげで、迷いなくコミットメッセージが思いつくようになったのが個人的には今回書いてて最大の収穫だった。たぶんカンニングペーパーを作る行為それ自体効率のいい学習になるという話と同じだと思う。

このまとめも100以上用例を転載してあるので、それを読むだけでも多少は効果があるんじゃないかと思う。同じようにコミットログ書きたくねぇなぁ英語わっかんねぇなぁと思っている人にとって、何か役に立つところがあれば幸いである。

 
ログイン ユーザー登録
ようこそ ゲスト さん