バージョン管理システム (TFS など) にコードを登録するときに、コメントを記述するためのガイドラインを作成する必要があります。
たとえば、バグ修正を提出するときは、「Fixed bug #...」というコメントを作成します。
このトピックについてブレインストーミングを試みましたが、ほとんどのアイデアは付加価値が少なすぎます。
これに関する提案をいただければ幸いです。
8 に答える
7
通常、私が職場で行うコメントは、行われた変更の簡単な概要です。短くシンプルなもの。
最初はあまり価値がないように見えるかもしれませんが、履歴をさかのぼって何かが変更された時期を見つけるときに非常に役立ちます (単なる「バグ #####」よりもはるかに便利です)。ソース管理の履歴に戻って、特定の動作やコードの一部がいつ変更されたかを確認する必要があったことが何度かありましたが、簡単な概要を使用すると、変更があった場所を簡単に追跡できます。バグ番号だけを入力すると、その基本情報を見つけるためにさらに多くの作業を行う必要があります (バグ トラッカーを起動してバグを見つけます)。
于 2009-05-12T20:55:39.513 に答える
7
このトピックに関する私の (かなり簡潔な) ガイダンスは、「何を変更するかではなく、なぜ変更を行っているかを文書化すること」です。
つまり、「MyClass.cs と FooBar.cs のバグを修正しました」と言うべきではありません。なぜなら、そのコメントはかなり無関係だからです。彼らは変更セットを見て、それらの詳細を見つけることができます。同様に、TFS では変更セットを作業項目にリンクするということは、コメントに作業項目の参照を含めることはかなり不必要であることを意味します。代わりに、「エディターの潜在的な XSS 脆弱性を修正しました」などの変更の理由を説明する短い文は、変更セットの大きな履歴を調べるときに読むのに最も役立つものです。
于 2009-05-13T01:02:49.493 に答える
4
リリース ノートに記載される変更については、変更セット コメントまたはリンクされたバグ レポート (存在する場合) に、提案されたリリース ノート エントリを含めます。
リリース ノートのエントリを書き出すと、一歩下がって、ユーザーの視点から編集内容を確認する必要があります。これにより、問題の内容と修正によって問題がどのように解決されるかを簡潔に説明することができます。
于 2009-05-12T21:42:28.313 に答える
2
TFS を構成して、すべてのコード チェックインに TFS タスクが関連付けられていることを要求できます。
私が働いているプロジェクト チームは、すべてのバグや機能をタスクとして TFS に入力し、コード チェックインを適用するタスクに関連付けることを要求しています。
コメントも必要ですが、変更を別のブランチにマージする必要がない場合を除いて、書く内容についての厳格なガイドラインはありません。
于 2009-05-12T20:59:39.693 に答える
1
可能な場合（バグ追跡やソース管理にTFSを使用する場合など）、チェックインを適切な作業項目に直接リンクします。それができない場合は、チェンジセットのコメントに作業項目/バグ番号を追加します。これは、チェンジセットコメントの最低限の許容レベルです。
チェックインコメントでは、変更の意図を説明し、必要に応じて変更が目的の結果を達成する方法の詳細のみを追加する必要があります。適切な作業項目のタイトルから始めることをお勧めします。
コメントのターゲットの長さは、1〜2文が適切です。あまり一般的ではありませんが、コメントは無意味です（たとえば、「xyzのバグを修正しました」）が、不必要な詳細のレイヤーの下に変更の意図を隠さないでください。
于 2009-06-06T10:16:24.517 に答える
1
変更に関連するチケットやバグがある場合、その場合は番号とタイトル (リンク付き) で十分です。
それ以外の場合は、どのような変更を実装したかを述べてください。定期的なコメントのガイドラインが適用されます。人気のあるプロジェクト ログをチェックして、良い例を確認できます。
于 2009-05-12T20:56:28.637 に答える
0
変更のコンテキストと動機を提供するため、可能であればバグへの参照 (チケット、問題、名前が何であれ) を含めることを好みます。また、何が変わったのか、なぜ変わったのかという質問には、できる限り 1 行で答えるようにしています。コメントをするときは、ログ、差分、チケットを振り返って、自分が何を考えていたのかを理解するために、6か月後の自分について考えるようにしています。あまりにも詳細に入ることは決して役に立たないようです。
于 2009-05-12T20:57:12.147 に答える
0
有益なはずのバグの問題のタイトルを貼り付けるための+1。
バグのタイトルに加えて、必要に応じてドキュメントの理由に+1。
お客様にお知らせしたいときのリリースノートを意識して+1。
SCM、バグ追跡、および CI を統合し、問題/バグでそれらを相互にリンクさせるための +1。
于 2010-04-09T11:32:29.960 に答える