ソースコードのコミットにコメントを追加するように、仲間の開発者にWANTを説得するにはどうすればよいですか？

Subversion（私たちが仕事で使用しているもの）は、コミットに関するコメントを要求するように設定できることを知っていますが、これを単純にオンにする力はありません。私はことを知っている私の唯一のメモリジョガーとして、急速にコミットの背後にある理由を理解するならば、それは、便利ですので、私のコミットをコメントした理由があります。ただし、これは私が常に受け取る2つの応答に対抗するには十分ではないようです。

1. 時間がかかりすぎて、変更をレポに入れたいだけです。
2. 差分を見るだけで十分です。

単にJIRA課題IDを入力することの価値と、それがどのように自動的に課題に結び付けられるかを示していますが、まだサイコロはありません。

最悪なのは、電話をかけることができる人が同じキャンプにいることです。気にする必要はなく、差分を見ることに問題ありません。

私はそれが正しいことだと知っていますが、どうすれば彼らに光を見せることができますか？仲間の開発者を納得させることができなくても、ビジネスのためにそれが正しいことだと経営者に納得させるにはどうすればよいですか？

「なぜ」に焦点を当てます。そのすべてが非常によく差分を見て、誰かがコードのセクションまたはそのようなものの論理的な流れを変えたのを見ましたが、なぜ彼らはそれを変えたのですか？理由は通常、関連チケット（JIRAの場合）にあります。

彼らはなぜ「なぜ」が重要なのか疑問に思うかもしれませんが、その変更のノックオン効果であるバグをキャッチした2年後には、なぜそれが行われたかを知ることは新しいバグを修正するだけでなく、古いバグが再び出現することはありません。

監査の理由もあります。コミットとチケットIDをバインドすると、本当に簡単に「OK」と言うことができます。バージョン2をプッシュします。これにより、欠陥23、25、26、27が修正されます。

彼らにマージを行わせ、サポートに対処させます。繰り返しますが、あなたはこれを行う立場にないかもしれませんが、以前のコミットの問題をトラブルシューティングするのが自分自身であることがわかった場合は、フェンスを越えて丁寧に送信して発言してください。コミットのコメントがないため、あなたが何をしたかわかりません。あなたはそれを理解するために必要なこれらの変更を加えました。

ブランチのマージにも。それがあなたに当てはまるかどうかはわかりませんが、それは私がコメントが役に立つと思った1つの領域です。

繰り返しますが、あなたの船ではありませんが、私がソフトウェアチームを管理したとき、彼らが良いコミットコメントをした場合、私は彼らに週ごとのステータスレポートの代わりにそれらを使用します。その後、すばらしいコミットを獲得し、マネージャーとして何が起こっているかを追跡するのが簡単になりました。

コードで改行とスペースを必要とするのと同じ理由で、チェックインコメントが必要です。物事を追跡しやすくするために、読んで理解することを理解してください。

比較する必要がある場合もありますが、多くの場合は必要ありません。開発者が2〜3文を読むだけで済む場合に比較を強制するのは、時間の無駄です。なぜ彼らは開発者の時間の価値を見ないのだろうか。

• 良い手本を示します。独自のコミットメッセージを有用性の輝かしい例にします。チームがストーリーや欠陥を管理するために使用する他のシステムへの参照を含めます。変更を要約した簡単な声明と、変更が必要な理由についての十分な説明を入れてください。
• 適切なコミットメッセージがないために余分な作業が発生するたびに、送信者に質問を投げてください。これに固執する（しかし、ジャークではない）。
• ロールを超えていない場合は、コミットメッセージを使用して毎日の変更ログを送信するスクリプトを作成します。これにより、有用なメッセージには改訂版を閲覧する以上の利点があるという議論の信頼性が高まります。彼らは日々何が起こっているかを見るので、これはあなたの側の管理を得るのを助けるかもしれません。
• 味方を特定します。あなたに同意する他の個人が少なくとも1人いることを願っています（おそらく黙って同意しないことによって）。その人またはそれらの人を見つけて、あなたが一人で立っていないように彼らをさらに説得してください。
• ちゃんとしたコミットメッセージがあなたの時間をどのように節約したか（または貧弱なメッセージがあなたの時間を犠牲にしてしまった）と言う機会が訪れたら、それをつかんでください。

きしむホイールになることを恐れないでください。他の人々の悪い習慣と戦うことは、しばしば消耗戦です。

これは私が聞いた中で最も奇妙な質問の一つでなければなりません。人々は何かを修正するのに何時間も、あるいは何日も費やし、コミットメッセージを入力するのに余分な2秒が長すぎます！私は、そのような近視眼的な人々と働くことを心配すると言わなければなりません。彼らは明らかに、彼らのツールを最大限の可能性に近づけることさえしていません。

先週私が関与したコードレビューの例を次に示します。バージョン管理ソフトウェアはマージ全体の履歴を保持しません。したがって、古い変更については、それが作成された正確なブランチを見つける必要があります。ブランチYには「ブランチZからマージされた」と表示される場合があり、実際には、いくつかのレベルのより深いネストのブランチには実際のコミットメッセージがあります。

新しい従業員は、履歴を正しく追跡する方法を知りませんでした。つまり、本質的には差分だけで作業していました。彼は、追跡しているバグに関連するコメントアウトされたコードを見ました。彼がコードのコメントを外したとき、彼のバグはなくなりました。彼は、デバッグ中に誰かがコードをコメントアウトし、誤ってチェックインしたと考えていました。

それはコードレビュー中に私たち二人にとって正しいとは感じなかったので、本当のコミットメッセージを追跡し、1年前にそのコードを削除する正当な理由があることを発見しました。新しい従業員は、古いバグを再導入することなく、新しく発見されたバグを修正するために自分のコードを修正することができました。

徹底的な単体テストなど、この種のリグレッションの導入を回避するより良い方法がありますが、どういうわけか、単体テストに2秒のコミットメッセージ「無駄な」時間を気にしない人はいません。

私はここでまったく同じ問題を抱えていたため、Subversionに事前コミットフックを追加して、ユーザーストーリー番号（予期される形式の基本的なパターンマッチング）で始まっていないコミットを受け入れないようにしました。

000-0000を入力するのを止めるものは何もありませんが、完全に受け入れられる数字を持っている場合、破壊的な馬鹿だけが数字を補います。

一連のユーザーストーリーがどのビルドに入ったのかを見つけようと何日も費やしてからこれを行いました。はい、それは他の場所でプロセスの失敗に対処することでしたが、それでも追跡することは信じられないほど貴重な情報です。

適切なコミットコメントは、適切なドキュメント、低速で機能しない脳のキャッシュ、または長時間のデバッグ/問題分析/調査の結果のキャッシュのようなものです。

たとえば、デバッグ、ログの分析など、何かを理解するのに時間を費やすときはいつでも、発見と結果は貴重です。もちろん、ほとんどのタスクを繰り返すことができますが、時間がかかる場合があります。そのため、常に結果を文書化する必要があります。

それでも、文書化には時間がかかり、「これを一度だけやればよいので、なぜそれを書き留めるのか」などのように、必要でないと感じることもあります。それは問題ありませんが、最初に結果を文書化しなかったため、同じことを2回行うとすぐに、結果を文書化することはもちろん賢明です。

同僚がコミットコメントを追加するのはあまりにも手間がかかると感じている場合、たとえば、少なくとも解決しようとしているJiraのケース/チケットを指す場合、それぞれの理由に関する質問に絶えず応答するというプレッシャーに動機付けられる可能性がありますチェンジセット。

私の意見では、ドキュメントは要求された情報の機能として作成されるべきです。たとえば、メール通信は非常に優れたドキュメントシステムです。質問は、後で取得できる回答を受け取ります。これが、メーリングリストとフォーラムがナレッジベースとして実際に機能する方法です。

残念ながら、私が働いている場所では、メールは3か月後に自動的に削除されるため、実際には常に機能するとは限りません。

許可ではなく、許しを求めてください。

厳しい間、私はちょうどこれをしました。私は、支持する人々と反対する人々の間で50/50の分裂がありました。そのほとんどはグループ内の私と同じレベルでした。議論は「わざわざできません」と「要点」でした。（どちらも無関心と怠を示しており、純粋な懸念ではありません）。

単に文字列の長さを測定し、拒否する前に少しユーモラスなメッセージを与えるプリコミットフックを追加しました。メッセージに自分の名前を入れたので、「この怒り」の責任が明確になりました。もちろん、「反対者」はそれを簡単に削除できますが、スクリプトを掘り下げるには、もう1つコメントを追加するよりも多くの労力が必要です。

1週間、* *（削除済み）またはkjhfkwhkfjhwのようなメッセージが追加されました。その後、基本的なメッセージが表示され始めました。

1年後、懐疑論者は卑劣なコメントを使用し、実際に彼らがどれほど近視眼的であったかを認めています。私はコンセンサスを得ることはできませんでしたが、私は確かに許しとおそらく信頼を得ました。それは機能し、人々はそれを使用します。

もっと気前よくなりたい（または問題が発生すると感じている）場合は、試用期間中にコミットフックを追加する許可を求めてください。2週間または4週間で人々がそれを好まない場合は、それを削除すると言います。可能性は、彼らは興味を失う...またはそれを好きに成長します。

私は通常、以下を介して人々を説得します。

• 正当な理由がある弁証法
• 例でリード
• 損耗

もし私たちのチームに何か悪いことをしてほしかったなら、私は自分の道を歩むまで悩み続けます。すでにXを実行していた場合、時間とお金を節約できたと指摘できる時期に、私は悩みます。

コミットコメントのその他の正当な理由：

• コメントからChangeLogを自動的に生成します。
• バグ修正、機能追加の監査証跡。これは、チームの内外で役立ちます。
• コミットメールをより便利にします。
• （ほとんどすべてのコミットの後に）開発者にコミットXが何をするかを尋ねるのを止めてください。

• 6か月前に作成された不明瞭なものについてSVNログを確認してください。
• いつ完了したかを言わずに、このことについていくつかの質問をする
• ???
• 利益

どのようにして彼らに良いコメントを追加させたいですか？

私がちょうどいた同僚との経験から。プロジェクトの最後に、プロジェクト全体で行われたすべての変更の概要ドキュメントを作成する必要がありました。私の同僚は、良いコミットノートを作成していなかったため、このタスクにかなり時間がかかり、コミットごとに非常に長いコメントを作成するようになりました。

つまり、重要なことは、プロジェクトの最後に、どのファイルにどのような変更が加えられたのか、どのファイルが追加/削除されたのか、そしてその理由を詳しく説明する要約文書を開発者に書くことです。

密室での管理にこれを提案する：

最悪のシナリオが発生します。上級レベルの開発者は全員出て行きます。

会社が空いている開発者の席を奪い合うと、管理チームはシステムの状態をクライアントに伝える任務を負います。

アプリの履歴を再構築する上で、仕事をより簡単にできると思うものを尋ねます。

システムの状態の変化を明確に説明する単純な英語のコミットメントを読んでいますか？

または、彼らはコードの違いを見て、自分でそれを理解することを好むでしょうか？

彼らを説得する一つの方法は、あなたが感じている痛みを実際に経験することだと思います。

たとえば、次の問題に取り組んでいるとしましょう。彼らにはバグがあり、同じコード（別の皮肉なことに）の別のバグ修正が実装されたときに何らかの形で現れました。コミットメッセージを検索するだけでこれを調べることができるのは素晴らしいことです（したがって、誰がそれを書いたかを見つけてください）。

別の方法は、コミットメッセージが何かが特定の方法で実装された理由についてのヒントを与えるのに役立つ可能性があることを説明することです。コミットメッセージが「機能X」とだけ言っても、それを実装した人の手がかりを得ることができるので、誰と話すべきかがわかります。

ただし、これは私が常に受け取る2つの応答に対抗するには十分ではないようです。

1. 時間がかかりすぎて、変更をレポに入れたいだけです。
2. 差分を見るだけで十分です。

他の開発者がコメントを投稿することで他の利益を得られるように、他の開発者に挑戦を投げかけましたか？いくつかの異なる角度のいずれかからこれを見ることができます：

1. ゲームをアップする-これは取るに足りない視点になる可能性がありますが、ここでのアイデアは、彼らが一定期間これを行い、アイデアに慣れることで、習慣が逆方向に行くには時間がかかることです。ここでのもう1つのポイントは、コメントがどれだけ精査されるかということです。コメントに短いストーリーが必要な場合は、その点を理解できます。
2. 変更の助成-これは、最初のバイインでこれを試す方法、またはしばらく変更を行うための何らかのインセンティブを提供する方法として、何らかのコンテストがある場所です。

他に考慮すべきことは、同僚の開発者があなたの職場をどのように管理しているかをどれだけよく知っているかということです。彼らが昨日10のことを成し遂げようとしているなら、彼らはすでに働いているものとして見ているものを変えたくないかもしれないことを理解できました。「いいえ、これは機能しませんか？」もしそうなら、私は彼らがこれに関して少し防御的または戦闘的であるかもしれない方法を見ることができます。「これはうまくいくかもしれませんが、もっと良い代替手段があります...」と伝えようとしているなら、チャンスがあるかもしれません。IMO、ここで「あなたよりも聖なる」態度をとることはあなたを助けません。

これを見る別の方法は、関係する開発者が自分のキャリアを成長させる方法としてです-彼らは彼らの仕事のドキュメントを所有するべきです。

上記の記事で取り上げられた他のポイントに加えて、コードの変更を確認して、変更が行われた場所/時期/理由を確認することができます。これは、とらえどころのないバグを追跡する際に不可欠です。

コミットにコメントすることが重要であると確信した後、コミットにコメントを強制するスクリプトを作成できます。そうしないと失敗します。最小限の文字を指定して、意味のあるコメントにすることもできます。これは、彼らが「思い出す」のに役立ちます。

しかし、@ Kevinが言ったように、なぜ彼らが理由を理解するか、または任意のランダムなコメントを追加するだけであることが重要です。

コードレビューはありますか？役立つ可能性のあることの1つは、コミットまたはマージは他の開発者によって確認および承認される必要があるというルールを制定することです。その後、あなたがレビュー担当者である場合、コミットを行っている開発者に彼が何をしたかを説明するよう依頼する必要があります。彼が行ったら、あなたが彼にあなたに言ったことをコメントにタイプするように彼に頼むべきです。多くの場合、行った変更を首尾一貫して説明できない場合、それはそれらの変更がそもそも行われてはならないことを意味します。

ただし、コメントをコミットするのと同じくらい明らかに有用なものに、どのように反対することができますか？それはまったく長くかかりません、そしてそれはよく費やされた時間です。コメントを書くと、あなたが今やったことについて考えるようになります。それはあなたが実際にあなたがしたと思うことをしたこと、そしてあなたが何も愚かなことをしていないことを確認するためにあなたが差分を見ることを引き起こすかもしれません。

あなたがコメントを書かないとき、あなたはだらしなくて、規律がありません。そして、あなたがコメントを書くことを要求されるべきでないと主張するなら、あなたは故意に過失です。

50,000行のメソッドの手続き上の混乱を維持する唯一の方法を彼らに伝え、その後、コードベースを肥大化する無意味なコメントの束を処理する必要がないように、将来、より適切でより明確なコードを書くことを検討してください。

これはプロセス変更項目です。コメントのQAを含むコードのみの品質保証チェックのために、マネージャーに「x」によって開発されたコードを「Y」に割り当てます。

私自身の組織では、開発者は自分のコードの最終QAを実行してチェックインすることを許可されていません。これは別の開発者が行う必要があります。QAチェックの一部はコメントなので、コメントもチェックインもありません。「アート」が実際に他の誰かの契約上の知的財産である場合、多くの契約作業を行うため、他の人がコードを理解して活用できる必要があります。また、長い休止の後、プロジェクトが私たちに戻ってくることがあります。18〜24か月後にコードを取得し、目の前のコードアーティファクトに到達した理由、場所、および方法を理解する必要があります。これにより、コミットコメントを書くための利己的な動機が提供されます。

仲間の開発者に依頼して、いくつかのマージを行い、履歴を検索し、履歴からいくつかのファイルを比較してもらいます。

翌日にはコメントをお願いすることがあります。

ここにいくつかのアドバイスがあります：

1. 世界を変えようとしないでください。あなたは失敗します。
2. 代わりに、皆がわずかに異なる方法で作業することを再認識すべきです。誰にでも合うサイズはありません。
3. 人々の作業プロセスにいくつかの特定の手順を要求することは非常に悪いことです。これらのプロセスの変更には10年かかります。次の期限までにこれを行うように依頼しています。
4. 単純なプロセスの変更でさえ時間がかかることがあります。
5. コミットに関する小さなコメントは、これらのプロセスを変更するにはあまりにも重要ではありません。
6. あなたは彼らが質の高い仕事をしていると仮定することができますが、ステップ自体を選択するのに十分な自由を与えるべきです。経験豊富な開発者にとっては、面倒な手順は必要ないかもしれません。
7. 初心者にベビーシッターをしている場合、より強力なプロセスが必要かもしれませんが、経験豊富な開発者はでたらめに対処すべきではありません。
8. 仕事のやり方に厳格な制限を課すことは決して機能しません、人々を遅くするだけです（彼らが速すぎる場合は良いかもしれません）
9. 自分のやり方が物事を行うための唯一の正しい方法だと考える人はたくさんいます。あなたが彼らの一人ではないことを願っています。

ソース管理で許可されている場合は、コメントなしのコミットを防ぐために、必須のコメントを有効にします。十分に簡単で、5秒のコメント入力は無痛であることに誰もがすぐに気付くでしょう。

ただし、コメント化されていないコミットは、最も小さなマイナスの1つです。私は、単一のコミットがコメントされなかった多くの成功したプロジェクトの一部でした。パンティーを束ねないでください。