構成管理-コードコメントの履歴

StackOverflow https://stackoverflow.com/questions/648972

質問

質問する前に、背景情報を少し教えてください：

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

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

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

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

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

誰かが私の議論に反対するかどうか知りたいです。変更管理システムやソース管理システムが提供できないコメント付きソースコード履歴の利点を逃していますか？

役に立ちましたか？

解決

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

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

他のヒント

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

ソース管理システムを2回変更した同様の方法で、大規模なプロジェクトに取り組みました。これらのコメントを喜んでくれた日はありませんでした。

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

もちろん、コードはバージョン管理下にあり、現在のソースコード（今日開いて読むことができるもの）は有効である必要があると常に考えていました現在時制でのみ。

過去および先月に最大6軸をサポートするように更新したレポートで最大3軸を持つことができるかどうかは関係ありません。現在のバージョンが簡単に理解できる限り、機能を拡張したかバグを修正したかは関係ありません。バグを修正するときは、修正したコードをそのままにしてください。

ただし、例外があります。 修正されたコードが以前の誤ったコードよりも直観的に見えない場合（およびその場合のみ）。明日誰かが来て、コードを読むだけで<！> quot;より正確だと思われる<！> quot; に戻そうと思うなら、コメントを追加するのが良いでしょう。 <！> quot;これは回避するためにこのように行われます...何とか何とか。<！> quot; また、背後にある問題がチームの文化内の悪名高い戦争物語である場合、または何らかの理由でバグレポートデータベースにコードのこの部分に関する非常に興味深い情報が含まれているため、 <！> quot;（Bug Id 10005を参照）<！> quot; を追加するのは間違っているとは思わない説明コメント。

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

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

1994年から96年にかけて、私が取り組んでいるコードにはフェーズがあり、ファイルの先頭に変更履歴コメントを挿入する傾向がありました。これらのコメントは意味がなく、役に立たなくなりました。そのようなコメントを含むファイルを編集するときに実行する多くの標準的なクリーンアップの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チームもコードを修正する必要がありました。コメントは助けになりました-バグが本物であることを保証します-がっかりします。

ライセンス： CC-BY-SA と 帰属
所属していません StackOverflow
scroll top