同僚の開発者にソースコードのコミットにコメントを追加するように説得するにはどうすればよいですか？
Subversion（仕事で使用しているもの）は、コミットに関するコメントを要求するように構成できることを知っていますが、これをオンにするだけの力はありません。 myコミットにコメントを付ける理由は、メモリジョガーとしてだけでも、コミットの背後にある理由をすばやく理解することが役立つためです。ただし、これは、私が常に得る2つの応答に対抗するには十分ではないようです。
- 時間がかかりすぎて、変更をリポジトリに取り込みたいだけです。
- 差分を確認するだけの簡単さです。
JIRA課題IDを入力することの価値と、JIRA課題IDが課題に自動的に結び付けられる方法を示していますが、それでもダイスはありません。
最悪の場合、canを呼び出す人は同じ陣営にいます：気になりたくないし、diffを見ても大丈夫です。
私はそれが正しいことだと知っていますが、どうすれば彼らに光を見せることができますか？仲間の開発者を納得させることができない場合でも、それがビジネスにとって正しいことであると経営陣にどのように納得させることができますか？
「なぜ」に焦点を当てます。差分をよく見て、誰かがコードのセクションなどの論理フローを変更したことがわかりましたが、なぜ変更したのですか？その理由は通常、関連するチケット（JIRA for you）にあります。
彼らはなぜ「なぜ」が重要であるのか疑問に思うかもしれませんが、2年間でその変更の影響であるいくつかのバグを見つけたとき、なぜそれが行われたのかを知ることは、新しいバグを修正するだけでなく、古いバグを再出現させることはありません。
監査の理由もあります。コミットとチケットIDをバインドすることで、大丈夫と言うのは本当に簡単になります。バージョン2をリリースします。これにより、欠陥23、25、26、27が修正されますが、欠陥24に対するコミットはないため、未解決です。
それらにマージを行わせ、サポートに対処させます。繰り返しますが、あなたはこれを行う立場にないかもしれませんが、以前のコミットからの問題をトラブルシューティングする責任があることに気付いたら、それをフェンスを越えて丁寧に送って言ってください。コミットコメントがないため、何をしたかわかりません。理解するために必要な変更を加えました。
ブランチのマージにも。それがあなたに当てはまるかどうかはわかりませんが、それは私がコメントが役立つと思った領域の1つです。
繰り返しますが、あなたのボートではありませんが、私がソフトウェアチームを管理しているときに、彼らが良いコミットコメントをするかどうかを彼らに伝えました。その後、優れたコミットを取得し、マネージャーとして何が行われているかを追跡するのが簡単になりました。
コードに改行とスペースが必要なのと同じ理由で、チェックインコメントが必要です。物事を追跡しやすくするために、読んで理解してください。
場合によっては、比較する必要がありますが、そうでない場合もあります。開発者が2〜3文を読むことだけが必要な場合に比較比較を強制するのは、時間の無駄です。なぜ開発者の時間の価値が見られないのでしょうか。
- 良い手本を示します。あなた自身のコミットメッセージを、有用性の輝かしい例にしてください。チームがストーリーと欠陥を管理するために使用する他のシステムへの参照を含めます。変更内容を要約した簡単な説明と、変更が必要な理由を説明し、すべての提出物にそれ以外のものを含めないでください。
- まともなコミットメッセージがないために余分な作業が発生する場合は、送信者に質問を投げてください。これに固執する（ただし、ジャークではない）。
- 役割を超えていない場合は、コミットメッセージを使用して毎日の変更ログを送信するスクリプトを記述します。これは、有用なメッセージにはリビジョンをブラウジングする以上の利点があるというあなたの主張に信頼性を与えます。これは、何が起こっているかを日々確認できるので、あなたの側で管理を行うのにも役立ちます。
- 味方を特定します。おそらく、あなたに同意する他の少なくとも1人の個人がいるでしょう（おそらく、黙って同意しないことによって）。その人またはそれらの人を見つけて、あなたが一人で立っていないようにさらに説得してください。
- まともなコミットメッセージによって時間を節約できた（または質の悪いメッセージによって時間を費やした）ことを説明する機会が現れたら、それを手に入れます。
きしむ車輪であることを恐れないでください。他の人々の悪い習慣と戦うことは、しばしば消耗戦です。
これは私が聞いた中で最も奇妙な質問の1つでなければなりません。人々は何かを修正するために何時間、あるいは何日も費やし、コミットメッセージを入力するための余分な2秒は長すぎる？！そんな近視眼の人たちと一緒に働くことを心配するつもりです。彼らは明らかにツールを使用していないため、最大限の可能性に近づいています。
先週私が関わったコードレビューの例を示します。私たちのバージョン管理ソフトウェアはマージ全体の履歴を保存しないため、古い変更の場合は、ブランチが作成された正確なブランチを見つける必要があります。それ以外の場合、コミットメッセージは「ブランチYからマージされた」のように表示されます。ブランチYは「ブランチZからマージされた」と表示される場合があり、実際には、いくつかのレベルのネストが深いブランチに実際のコミットメッセージがあります。
新入社員は、履歴を正確に追跡する方法を知りませんでした。つまり、基本的には差分だけで作業していました。彼は、追跡しているバグに関連するコメントアウトされたコードをいくつか見ました。彼がコードのコメントを外すと、彼のバグは消えました。彼は、誰かがデバッグ中にコードをコメント化し、誤ってチェックインしたと想定しました。
コードレビューの間、私たちの何人かにはそれが適切であるとは思われなかったので、実際のコミットメッセージを追跡したところ、1年前にそのコードを削除する正当な理由があることがわかりました。新しい従業員はコードを修正して、古いバグを再導入することなく、新しく発見されたバグを修正することができました。
完全な単体テストのような、こうした種類のリグレッションの導入を回避するより良い方法がありますが、どういうわけか、単体テストで2秒のコミットメッセージの「無駄」な時間を気にできない人は見当たりません。
ここでまったく同じ問題が発生したため、Subversionに pre-commit フックを追加しました。これにより、ユーザーストーリー番号で開始されなかったコミットを受け入れないようになります（予想されるいくつかの基本的なパターンマッチング）フォーマット）。
彼らが000-0000に入るのを止めるものは何もありませんが、完全に許容可能な数がある場合、破壊的なばかだけが数を構成することになります。
ユーザーストーリーのセットがどのビルドに含まれるかを見つけるために何日も費やした後、私はこれを行いました。はい、それは他の場所でプロセスの失敗に対処することでしたが、それでも追跡するのに信じられないほど貴重な情報です。
適切なコミットコメントは、適切なドキュメント、遅くて機能しない頭脳のキャッシュ、または長いデバッグ/問題分析/調査の結果のキャッシュのようなものです。
例えば。デバッグ、ログの分析など、何かを理解することに時間を費やすたびに、発見と結果は貴重です。もちろん、ほとんどのタスクは繰り返すことができますが、時間がかかる場合があります。したがって、常に結果を文書化する必要があります。
それでも、ドキュメンテーションには時間がかかり、「これを一度だけ実行する必要があったので、それを書き留める必要がある」など、必要がないと感じることもあります。それは問題ありませんが、最初に結果を文書化しなかったために同じことをもう一度行うとすぐに、結果を文書化することはもちろん賢明です。
したがって、たとえば、少なくとも解決しているJiraケース/チケットをポイントするなど、コミットコメントを追加するのが面倒であると同僚が感じた場合、彼らはそれぞれの理由に関する質問に絶えず回答するというプレッシャーに動機付けられる可能性があります。チェンジセット。
私の意見では、ドキュメントは要求される情報の関数として作成されるべきです。たとえば、メール通信は非常に優れたドキュメントシステムです。質問は、後で取得できる回答を受け取ります。つまり、メーリングリストとフォーラムは、知識ベースとして実際に機能します。
残念ながら、私が働いている場所では、メールは3か月後に自動的に削除されるため、実際には常に機能するとは限りません。
許可ではなく、許しを求めてください。
厳しい間、私はこれをやった。私は支持する人々と反対する人々の間で50/50の割合で分割しました。そのほとんどはグループの私と同じレベルでした。議論は「気にならない」「要点は？」だった。 （本当の懸念ではなく、無関心と怠惰を示しています）。
文字列の長さを単に測定するpre-commitフックを追加し、拒否する前に少しユーモラスなメッセージを出しました。メッセージに自分の名前を入れたので、「この怒り」の責任が明確になりました。もちろん、「反対派」はそれを簡単に削除できますが、スクリプトを掘り下げるには、コメントを1つ追加するよりも多くの労力が必要です。
1週間、* *（完全に削除された）またはkjhfkwhkfjhwのようなメッセージが追加されました。その後、基本的なメッセージが表示され始めました。
1年後、懐疑論者は意味のあるコメントを使用し、実際に彼らがどれほど近視眼的であったかを認めます。私はコンセンサスを得ることはできなかったでしょうが、確かに私は許しとおそらく信頼を得ました。それは機能し、人々はそれを使用します。
より親切になりたい場合（または問題が発生する可能性がある場合）、試用期間にコミットフックを追加する許可を求めます。 2週間または4週間で人々が気に入らなければ、それを削除するとします。おそらく、彼らは興味を失うでしょう...またはそれを好きになるまで成長します。
私は通常、人々を説得します：
- 正当な理由がある弁証法
- 例によって主導
- 消耗
もし私たちのチームに何か悪いことをさせたいと思ったら、自分の道にたどり着くまで困っていきます。私は、Xをすでにやっていれば、時間とお金を節約できたと指摘できる時期に、私はせっかちにしようとします。
コミットコメントのその他の正当な理由：
- コメントからChangeLogを自動的に生成します。
- バグ修正、機能追加の監査証跡。これは、チームの内外で役立ちます。
- コミットメールをより便利にします。
- （ほとんどすべてのコミットの後で）コミットXが何をするのかを開発者に尋ねないでください。
- 6か月前に作成された不明瞭なものがないか、SVNログを確認してください。
- いつ行われたかは知らせずに、このことについて質問します
- ???
- 利益
良いコメントを追加するにはどうすればいいですかwant？
たった今の同僚との経験から。プロジェクトの最後に、プロジェクト全体で行われたすべての変更の要約ドキュメントを作成する必要がありました。良いコミットノートを作成していなかったため、同僚はこのタスクに時間がかかることに気付き、コミットごとに非常に長いコメントを作成するようになりました。
したがって-要点-1つの解決策は、プロジェクトの最後に、開発者に、どのファイルにどのような変更が加えられたか、どのファイルが追加/削除されたか、その理由を詳しく説明する要約ドキュメントを書くことです。
これを密室の裏側の管理者に提案します。
最悪のケースのシナリオが発生します。すべての上級レベルの開発者がドアを出て行きます。
会社が空の開発者シートを埋めるためにスクランブルをかけているとき、管理チームはシステムの状態をクライアントに伝える役割を担っています。
アプリの履歴を簡単に再構築できるようになると考えていることを質問します。
システムの変化する状態を明確に説明する単純な英語のコミットメントを読んでいますか？
それとも彼らはコードの違いを見て自分でそれを理解することを好みますか？
これを見る別の方法は、関係する開発者がキャリアを成長させる方法としてです-彼らはownドキュメント 彼らの仕事の。
上記の記事で指摘された他のポイントに加えて、コードの変更を確認して、変更が行われた場所/時期/理由を確認することができます。とらえどころのないバグを追跡するときに、それは非常に重要です。
彼らを納得させる1つの方法は、あなたが感じている痛みを実際に経験することだと思います。
たとえば、次の問題に取り組んでいるとします。彼らにはバグがあり、同じコードに対する別のバグ修正（皮肉なことに）が実装されたときに、どういうわけか現れました。コミットメッセージを検索するだけでこれを調べることができればすばらしいでしょう（そして誰がそれを書いたかを見つけてください）。
別の方法は、なぜ何かが特定の方法で実装されたのかについてのヒントを与えるために、コミットメッセージが役立つ可能性があることを説明することです。コミットメッセージに「機能X」とだけ書かれている場合でも、それを実装した手がかりが得られるので、誰と話すかがわかります。
しかし、これは私がいつも得る2つの応答に対抗するには十分ではないようです。
- 時間がかかりすぎて、変更をリポジトリに取り込みたいだけです。
- 差分を見るだけで十分です。
コメントを入力することで他の開発者が他のメリットを得られるように、他の開発者に挑戦を投げかけてみましたか？いくつかの異なる角度からこれを見ることができます：
- ゲームを上向きにする-これはより難しい見方ですが、ここでのアイデアは、彼らが一定期間これを行い、そのアイデアに慣れることで、習慣が逆になるのに時間がかかるようになることです。ここでのもう1つのポイントは、コメントがどの程度精査されるかです。コメントで短編小説が欲しいなら、私は彼らの要点を理解することができました。
- 変更への助成-これは、最初の賛同を得てこれを試すか、しばらくの間変更を行うための他の種類のインセンティブを提供する方法として、ある種のコンテストを行う場所です。
他に考慮すべきことは、同僚の開発者があなたの作業場所を管理していることをどれだけよく知っていますか？彼らが昨日10のことを成し遂げようとしているなら、私は彼らがすでに機能しているものとして彼らが見ているものを変えたくないかもしれないことを理解できました。 「いいえ、これはうまくいきませんか？」もしそうなら、私は彼らがこれに関して少し防御的または戦闘的であるかもしれないことを見ることができます。 「これでうまくいくかもしれませんが、もっと良い代替方法があるかもしれません...」と伝えようとしている場合は、チャンスがあるかもしれません。ここで「あなたよりも崇高」な態度をとっても、IMOの助けにはなりません。
ここにいくつかのアドバイスがあります：
- 世界を変えようとしないでください。あなたは失敗するでしょう。
- 代わりに、全員がわずかに異なる方法で作業することを認識し直す必要があります。誰にでも合うフリーサイズはありません。
- 人の作業プロセスに特定の手順を要求することは非常に悪です。これらのプロセスの変更には10年かかります。あなたは彼らに次の締め切りの前にこれをするように求めています。
- 単純なプロセス変更でも、長い時間がかかる可能性があります。
- コミットに関するいくつかの小さなコメントは、これらのプロセスを変更するにはあまりにも重要ではありません。
- あなたは彼らが質の高い仕事をしていると仮定することができますが、自分でステップを選択するのに十分な自由を与えるべきです。経験豊富な開発者にとって、面倒な手順は必要ないかもしれません。
- 初心者をベビーシッターにする場合は、より強力なプロセスが必要になる場合がありますが、経験豊富な開発者はでたらめに対処するべきではありません。
- 仕事をしなければならない方法に厳しい制限を課すことは決してうまくいくことはありません、それは人々を遅くするだけです（彼らが速すぎる場合は良いかもしれません）
- 自分のやり方が唯一正しい方法であると考える人はたくさんいます。あなたが彼らの一人ではないことを願っています。
ソース管理がそれを提供する場合は、コメント化されていないコミットを防ぐために必須コメントをオンにします。十分にシンプルで、コメントを入力する5秒は痛みがないことにすぐに誰もが気付くでしょう。
しかし、コメント化されていないコミットは、存在する最も小さな欠点の1つです。私は、単一のコミットがコメントされなかった多くの成功したプロジェクトの一部でした。パンティーを束に入れないでください。
コードベースの肥大化した無意味なコメントの束に対処する必要がないように、50,000の行メソッドの手続き上の混乱を維持する機会を得る唯一の方法を彼らに教えてください。
仲間の開発者にいくつかのマージを行い、履歴を調べて、履歴からいくつかのファイルを比較するよう依頼してください。
おそらく彼らは翌日以降にコメントを入れるように頼むでしょう。
コミットにコメントすることが重要であると彼らに納得させた後、コミットにコメントを強制するスクリプトを作成できます。そうしないと失敗します。最小限の文字を指定して、意味のあるコメントを保証することもできます。これは、彼らが「覚えておく」のに役立ちます。
ただし、@ Kevinが言った理由を理解することが重要です。そうしないと、ランダムなコメントが追加されるだけです。
コードレビューはありますか？役立つ可能性があることの1つは、コミットまたはマージを他の開発者が確認および承認する必要があるというルールを設定することです。次に、あなたがレビュー担当者である場合、コミットを行う開発者に、彼が何をしたかを説明するよう依頼する必要があります。彼がそうしたら、彼にあなたがちょうど言ったことをコメントにタイプするように彼に頼むべきです。多くの場合、加えられた変更を首尾一貫して説明できない場合、それはそれらの変更が最初に行われるべきではなかったことを意味します。
私は言わなければなりません、コミットコメントと同じくらい明らかに役立つ何かに人々はどのように反対することができますか？そんなに時間がかからず、よく過ごす時間です。コメントを書くと、あなたはそれがあなたがたった今何をしたかについて考えることを強いられます。それはあなたがあなたが本当にあなたがあなたがやったと思うことをやったこと、そしてあなたが愚かなことを何もしていないことを確かめるために差分を見ることさえ引き起こすかもしれません。
あなたがコメントを書かないとき、あなたはずさんで規律のないです。そして、あなたがコメントを書くことを要求されるべきではないと主張するならば、あなたは故意に過失です。
これはプロセスの変更項目です。コメントのQAを含むコードのみの品質保証チェックのために、マネージャーに「x」によって開発されたコードを「Y」に割り当ててもらいます。
私の組織では、開発者が自分のコードの最終QAを実行してチェックインすることは許可されていません。これは別の開発者が行う必要があります。 QAチェックの一部はコメントなので、コメントもチェックインもありません。私たちの「アート」は実際には他者の契約上の知的財産である多くの契約作業を行っているため、他の人がコードを理解して活用できるようにする必要があります。また、プロジェクトが長い休止期間の後に戻ってくる場合もあり、18〜24か月後にコードを取得し、なぜ、どこで、どのようにして私たちの前のコードアーティファクトに到達したのかを理解する必要があります。これはコミットコメントを書くための利己的な動機を提供します。