コードの変更を文書化するさまざまな方法は何ですか？私は現在、多くの変更が行われているコードに取り組んでいます。コードの変更を文書化するための現在の規則は、次のようなものです。
//Begin add by xxxx for feature/bug xxxx <Date>
........
........
//End add by xxxxx for feature/bug XXXX <Date>
このずさんなコメント方法は、多くの混乱を引き起こしました。太いコメントから実際のコード行を探します。バージョン管理ソフトウェアのチェックインコメントセクションに変更を記録したくありません。すべての変更が文書化されているファイルの先頭に変更ログを保持することを考えています。変更を文書化するために皆さんが使用する方法は何ですか？
実際には、重要な情報は、コードがどのように到達したかではなく、コードが現在実行していることであることがわかります。これらの種類のコメントで現在のコードを隠すことにより、コードを読みにくく、操作しにくくします。
戻って何かが行われた理由を確認する必要がある場合は、すべての情報をバージョン管理でキャプチャするのが最適です。コード自体に履歴を取り込もうとしないでください。
バージョン管理システムは、変更情報の主なソースである必要があります。コード内の非自明な機能に関するコメントは、理由に関係なく、つまり変更のためであるかどうかに関係なく、コメントとして文書化する必要があります。
コードを変更したプログラマー、変更の理由となった関連するバグ/機能、および変更の時刻はすべて、バージョン管理システムが作成するファイルの変更ログにすでにエンコードされています。これ以上手動で変更ログを追加すると、古くなり、ファイルが乱雑になります。
私はこれをコードで行うことは決してありません。決して。コメントは最小限にする必要があります。また、コード内の紛らわしいロジックをより明確にするため（または、より頻繁に、規則を指摘するため）にする必要があります。各変更は常に個別にコミットしてください。簡潔な最大79文字のコミットメッセージを記述します。再構成されたテキスト（例：CHANGES.rst）を各パケット（製品）のルートに保持できます。それが私たちのやり方です-あなたはここで見ることができます。
チケット/午後システムを使用して、コミットメッセージでチケットに言及することもできます。