6

質問をする前に、少し背景情報を提示させてください。

私は最近、ソース管理や変更管理システムなどの構成管理に Rational ツールを使用する新しいソフトウェア開発グループに参加しました。これらのツールに加えて、チームには、次のようなコードの変更をコード内のコメントとして記録するという標準的な慣行があります。

///<history>
   [mt] 3/15/2009  Made abc changes to fix xyz
///</history>

コメント標準の公式の目的は、「コメントは要件からコード変更までのトレーサビリティを提供する」ことです。

私は、この慣行は不必要で冗長であるという議論を提起する準備をしています。チームはこの標準をすぐに取り除く必要があります。

つまり、変更管理システムは、要件からコード変更までの追跡可能性を構築する場所であり、ソース管理はバージョン間の差分を実行することで変更の詳細な履歴を提供できます。ソース コードがチェックインされると、対応する変更管理チケットが記録されます。CM チケットが解決されると、どのソース コード ファイルが変更されたかが記録されます。これは、望ましいトレーサビリティのための十分な相互参照を提供すると思います。

私の主張に反対する人がいるか知りたいです。変更管理およびソース管理システムでは提供できない、コメント付きのソース コード履歴の利点が失われているのでしょうか?

4

6 に答える 6

8

私自身、そのようなコメントは価値があるよりも厄介であることにいつも気付きました: マージの競合を引き起こす可能性があり、2 つのバージョン間の差分を分離しようとしているときに「誤検知」として表示される可能性があり、コードの変更を参照する可能性があります。その後の変更によって廃止されました。

メタデータを失わずにバージョン管理システムを変更することは、多くの場合 (常にではありませんが、多くの場合) 可能です。これをサポートしていないシステムにコードを移動する場合、カットオーバーの前に変更履歴をコメントに変換するスクリプトを作成することは難しくありません。

于 2009-03-16T01:59:25.310 に答える
4

コメントを使用すると、差分やバージョン管理システムの複雑さを掘り下げることなく、コード内のすべての変更とその理由を適切な場所で見つけることができます。さらに、バージョン管理システムの変更を決定した場合、コメントは残ります。

私は、ソース管理システムを2回変更した同様の慣行を持つ大規模なプロジェクトに取り組みました。このようなコメントをいただけて嬉しくない日はありませんでした。

冗長ですか？はい。不要ですか？いいえ。

于 2009-03-16T01:44:10.667 に答える
2

もちろん、コードはバージョン管理下に置かれるべきであり、現在のソースコード(今日開いて読むことができるもの)は現在形でのみ有効であるべきだと常に考えてきました。

過去にレポートに最大 3 つの軸を含めることができ、先月、最大 6 つの軸をサポートするようにレポートを更新したかどうかは問題ではありません。機能を拡張したり、バグを修正したりしても、現在のバージョンが簡単に理解できるものであれば問題ありません。バグを修正するときは、修正したコードを残すだけです。

ただし、例外があります。修正されたコードが以前の間違ったものよりも直感的でないように見える場合 (およびその場合にのみ)。誰かが明日来るかもしれないと感じ、コードを読んだだけで「より正しいと思われる」コードに戻したくなる場合は、コメントを追加するとよいでしょう。何とか何とか。」また、背後にある問題がチームの文化に内在する悪名高い戦争の話である場合、または何らかの理由でバグ レポート データベースにコードのこの部分に関する非常に興味深い情報が含まれている場合は、"(Bug Id を参照)を追加しても間違いではありません。 10005)」を説明コメントに。

于 2009-03-16T08:08:36.653 に答える
1

真っ先に思い浮かぶのは、ベンダー ロックインです。Rational から離れたことがある場合は、移行中にアーティファクトのバージョンだけでなく、完全な変更履歴が維持されていることを確認する必要があります。

于 2009-03-16T01:44:34.627 に答える
1

コードにいるときは、なぜそのように構造化されているのかを知る必要があります。したがって、コードのコメントです。コードの外側にあるツールは、たとえそれが良いものであっても、有用であるためには脳内であまりにも多くのコンテキスト シフトを必要とします。それに加えて、ドキュメンテーションと diff からコードの意図をリバース エンジニアリングしようとするのはかなり難しいので、いつでもコメント行を読みたいと思っています。

于 2009-03-16T01:54:47.193 に答える
0

私が取り組んでいるコードには、1994 年から 1996 年にかけて、ファイルの先頭に変更履歴のコメントを挿入する傾向があったフェーズがありました。これらのコメントは今や無意味で役に立たないので、そのようなコメントを含むファイルを編集するときに私が実行する多くの標準的なクリーンアップの 1 つは、コメントを削除することです。

対照的に、変更が加えられた場所にバグ番号が付いたコメントもいくつかあり、通常、ばかげたコードがそのままである理由を説明しています。これらは非常に役立ちます。バグ番号は、情報を探すための別の場所を提供し、犯人 (または被害者 - さまざま) を特定します。

一方、このようなアイテムは本物です。先週片付けました - 歯を食いしばってください。

    if (ctab->tarray && ctab->tarray[i])
#ifndef NT
      prt_theargs(*(ctab->tarray[i]));
#else
      /* Correct the parameter type mismatch in the line above */
      prt_theargs(ctab->tarray[i]);
#endif /* NT */

NT チームは正しく呼び出しました。プラットフォーム固有の修正だと彼らが考えた理由は、私にはわかりません。もちろん、これまでコードがパラメーターなしの宣言だけでなくプロトタイプを使用していた場合、Unix チームはコードも修正する必要がありました。コメントは助けになりました-バグが本物であることを保証しました-しかし、腹立たしいです。

于 2009-03-16T02:28:59.683 に答える