コードにコメントすることについて多くの議論がありますが、チェックインにコメントするのはどうでしょうか?
このブログ投稿を見つけました: http://redbitbluebit.com/subversion-check-in-comment-great-practices/
リリース ノートをまとめる担当者として、私はその作業を簡単にする方法を探しています。
<Begin_Doc>...<End_Doc>現在、ソフトウェアの顧客に公開する必要があるものに対して、独自のスキームを定義しています。しかし、内部的なものであっても、すべての変更の「理由」を知りたいです。
すべての機能には、チケット/問題/バグレポート/タスク/呼び名があり、チケット番号は常にチェックイン コメントで参照されます。これにより、コンテキストが提供されます。
このためにバージョン管理システムを使用/過負荷にしないことをお勧めします。問題追跡ソフトウェアの方が適していると思います。
1 つには、要件ドキュメントまたは問題/欠陥システムに既にあるコミット メッセージにすべてのコンテキストと重複した情報を開発者に追加させるのは適切ではないようです。
ツールを使用して、コミット コメントにある関連する修正/問題番号を収集し、他のリポジトリからそれらを収集することができますが、基本的に改訂ツールを外部向けのものにするのは間違いだと思います。
ソース/バージョン リポジトリ/SVN が何であるかを定義する必要があります。ソース ファイルを管理するためのものなのか、それともリリース ノートを書くためのものなのか。過積載はいけないと思います。
簡潔にするように心がけています。コミットしようとしている変更を説明する 1 つの文を書きます。開発者がコミットを説明するために 2 つ以上の文を必要とする場合、コミットはおそらく 2 つの無関係な作業です。このようなコミットがバージョン管理で終わると、修正を単独で元に戻すことは困難になります。
コミット コメントに含めたいもう 1 つの情報は、コミットが修正 / 実装する欠陥 / 機能番号です。私たちが行うすべての作業が問題追跡システムの欠陥に関連しているわけではないため、これは必須ではありません。
コミット コメントに入れる最後の情報は、1 人のコード レビュアーの名前です。これは、コミットが行われる前に変更の健全性チェックを行った人物です。
機能的なコメントをお勧めします。コメントは、何が変更されたかの要約を提供する必要があります。何かが変更された場合、その理由。すべてのコミットは説明可能であるべきです。明確に説明できない場合は、おそらくチェックインすべきではありません。
ソース管理ログを使用する際に覚えておくべき最も重要なことは、いつ、何が変更されたかを判断するために存在するということです。より機能的で詳細なほど良い。コミットは、一口サイズのコメントで説明できる一口サイズの断片で行う必要があります。
私の個人的な好みは次のスタイルです。
エラーログシステムを更新しました。
重要なのは、コメントをどうするかです。リリース ノートを作成している場合は、提案どおりに行うことができます。ただし、代わりに、プロジェクト管理ツールやバグ追跡ツールなど、別の場所でリリース ノートを追跡することをお勧めします。
開発者関連のコメントについては、通常、何をしているのかを 1 文で説明するようにお願いしています。あまり形式張る必要はありません。さらに、誰がそれをしたかを知っていて、簡単なコメントがある場合は、通常、問題をさかのぼってその人を見つけることができます.
同様に、FogBugzなどのツールを使用すると、SVN チェックインをケース番号にリンクできます。つまり、ケースを検索して、完全なディスカッション、コメント、スクリーンショットなどを取得できます。これは、チェックイン コメントに入力できるよりもはるかに多くの情報です。
Remembrance に同意しますが、変更/バグ修正をそのように実装した理由についても少し書く必要があります。頻繁にチェックインすることを信じている場合は、同僚の 1 人がタスクを完了できるようにするために、TO DO も含める必要があります。
変更を小さくすることは役に立ちます。このように変更の詳細な説明を提供できます。
チェックイン コメントは、開発者が必要とする情報である必要があります。これには、リファクタリング、コードの背後にある動機などが含まれます。
私たちのプロジェクトでは、コミットとは何かについての詳細を提供し、Trac を使用してリポジトリを統合している問題のような情報を複製する必要がないようにすることを常に推奨しています。利点は、コメントで課題チケットを参照し、解決策または実行された作業手順のみを述べることができることです。次に、Trac は参照番号を元の課題番号に自動的にリンクし、コミット メッセージをコメントとして課題に適用します。次に、何が行われたかを確認したい場合は、Trac 内の問題を読むだけで、完全なコンテキストを取得できます。
リリース ノートに関しては、リリース内の問題のリストを取得し、コミット情報をコメントの基礎として使用するとうまくいくことがわかりました。通常、クライアントはコメントに含まれる可能性のあるすべての小さな変更や詳細レベルさえ気にしないため、未加工のコミット メッセージを含むリリース ノートはありません。そのため、通常は、そのリリースで実装された主な変更点とバグ修正を強調するために、かなりの量の編集を行う必要があります。
チェンジログのスタイルに従うようにしようと思います。最初の行は短い要約で、問題/チケット番号 (ある場合) を含めます。VCS が複数行のコミット メッセージを処理する方法に応じて、この後に空白行が続き、その後に複数行の詳細な説明が続きます。頻繁なコミットを思いとどまらせるので、厳密なフォーマットを強制するのは不合理だと思いますが、重要なコミット (問題を解決するもの、または大きな変更) がこの方法で行われている限り、問題はありません。
Trac や roundup + svn 統合などを使用すると、コミット メッセージから課題番号を取得できます。これらは非常に便利なので、常に最初の行に配置します。
編集：これが私の最も否定的な答えであることを考えると、最後の段落に隠されていることを強調する価値があると思います：私は個人事業主です。私はこれらのプロジェクトの100％の所有権を持っており、他の開発者とは協力していません。複数の開発者がいるショップでは、この回答で私が言っていることはすべて完全に不適切である可能性があります。
私はすべてのものと同じようにここでDRYを購読します。
コミットにコメントを追加することはほとんどありません。コメントはほとんどいつも自分自身を繰り返しています。「このコミットで何が変わったのか」という質問への答えは？ほとんどの場合、差分にあります。
ファイルを見て「ここで何が起こったのか」と尋ねると、最初に行うのは前のリビジョンとの差分を確認することです。90％の確率で、コードが自明であるか、コードにコメントした自明ではない何かがあったために、答えはすぐに明らかになります。そうでない場合は、ファイルの改訂日をバグ追跡システムと関連付けます。答えはそこにあります。
これは常に機能します。コードに適切なコメントを付けていなかったため、何かを理解するために少し調査が必要になることがあります。しかし、私は答えをかなり早く見つけることができなかったことがありません。
コミットログにコメントを追加するのは、差分が役に立たないことがわかっているときだけです。たとえば、クラスのメンバーを並べ替えるとき、diffがその場合に教えてくれるのは、非常に大きなことが起こったということだけです。その場合、修正したらすぐにファイルをコミットします。ファイル内にそのスコープの変更をコメントする適切な場所がないため、このリビジョンでの唯一の変更はメンバーの並べ替えであるという趣旨のコメントを追加します。
（「ファイルの先頭にある改訂履歴にそのような変更をコメントしてみませんか？」と質問されるかもしれません。ファイルの先頭に改訂履歴を保持していません。それは恐ろしい、壊れたものでした-生涯の習慣を変えるために、私はそれを一瞬後悔したことはありません。改訂履歴はSubversionです。）
私がプロジェクトの100％の所有権を持っていなかった場合、それは異なる可能性があります。コミットとバグ修正を関連付けるのは難しいかもしれません。バージョン管理に効果的に依存できるスタイルにコーディングするように他の開発者をトレーニングするのは難しいかもしれません。私は見なければならないでしょう。