comments - 削除されたコメントコード

Question

削除されたコードにコメントを付けることは良い習慣ですか? 例えば：

// Code to do {task} was removed by Ajahn on 10/10/08 because {reason}.

ピアレビュー中に私の開発者グループの誰かが、削除するコード行にコメントする必要があると指摘しました。役に立たないコメントでコードが雑然としているので、これはひどい提案だと思いました。私たちのどちらが正しいですか？

score 106 · Accepted Answer

一般に、削除されたコードにはコメントを付けるべきではありません。これは、コードベースが乱雑になるためです (そして、なぜ存在しないものにコメントを付ける必要があるのでしょうか?)。

欠陥追跡システムまたはソース管理管理ツールは、そのようなコメントが属する場所です。

score 29 · Accepted Answer

コードを (削除する代わりに) コメントアウトすることが良い考えである (まれな) 状況がいくつかあります。これが1つです。

適切で必要と思われるコード行がありました。後で私はそれが不必要で有害であることに気付きました. 行を削除する代わりに、別のコメントを追加してコメントアウトしました:「以下の行は、そのような理由で間違っています」. なんで？

コードの次の読者は、最初にこの行がないことをエラーと考え、追加し直そうとするだろうと確信しているからです。(読者が今から 2 年後の私であったとしても。) 私は、彼が最初にソース管理に相談するとは思っていません。このトリッキーな状況について彼に警告するためにコメントを追加する必要があります。そして、間違った行とそれが間違っている理由を持っていることが、たまたまそうするための最良の方法でした.

score 14 · Accepted Answer

コメントでコードを削除したままにしておくのは得策ではないことに同意します。

コードの履歴は、古いコードと、それが削除された理由を見つけることができるバージョン管理システムを通じて表示する必要があります。

score 8 · Accepted Answer

コードは常に削除する必要があります。

古い/削除されたコードを見ることができるということに関しては、それがリビジョン管理です。

score 6 · Accepted Answer

削除理由にもよります。

コメントは、将来コードを保守する人々へのヒントと考えています。コードがそこにあったが削除されたという情報が、コードを保守している誰かに役立つ場合 (おそらく「それをしないでください」のサインとして)、そうすべきです。そこにいる。

それ以外の場合は、コードの変更ごとに名前と日付を含む詳細なコメントを追加すると、全体が判読できなくなります。

score 4 · Accepted Answer

それはかなり役に立たず、コードが読みにくくなると思います。数ヶ月後にどうなるか考えてみてください....

// removed because of this and that
/* 
      removed this stuff because my left leg...
*/
 doSomething();
// this piece of has been removed, we don't need it...

何が起こっているのかを調べるのに30分かかります

score 3 · Accepted Answer

問題は、なぜコードを削除するのかということです。

無駄ですか？そもそも入れたのが間違い？

私の観点からのコメントは必要ありません。

score 2 · Accepted Answer

唯一の反対意見として、特別な状況でコードをコメントアウトする場所があると言います。場合によっては、その古いコードを介して実行されたデータが引き続き存在することがあります。最も明確なことは、その古いコードをソースに残すことです。そのような場合、古いコードが単にコメントアウトされた理由を示すメモはほとんど残さないでしょう。後にやってくるプログラマーは、古いバージョンをチェックする必要性を精神的に検出する必要なしに、まだ存在しているデータを理解することができます。

しかし、通常、コメントアウトされたコードは完全に嫌なものであり、遭遇したときに削除することがよくあります。

score 2 · Accepted Answer

コメントアウトされたコードを残すべきではない理由について、コメントアウトしたコードを残すべきではない理由について、ここでは誰も詳しく書いていません。その最大の理由は、コードが機能しなくなる可能性が高いことだと思います。誰もそれをコンパイルしていません。誰も単体テストを実行していません。人々が残りのコードをリファクタリングするとき、彼らはそれをリファクタリングしていません。ですから、すぐに使い物にならなくなります。または、役に立たないよりも悪いことに、誰かがコメントを外し、それが機能することを盲目的に信頼する可能性があります。

プロジェクトでまだ重い設計/開発を行っている場合は、コードをコメントアウトすることがあります。この段階では、通常、適切なアプローチを探して、いくつかの異なるデザインを試しています。また、以前に試みたアプローチが正しい場合もあります。そのため、そのコードがソース管理の奥深くで失われないのは素晴らしいことです。しかし、デザインが決まれば、古いコードは取り除きます。

score 2 · Accepted Answer

デバッグ時には便利ですが、そのようにコードをチェックインする理由はありません。ソース管理の要点は、コメントアウトされたコードでコードを乱雑にすることなく、古いバージョンを回復できることです。

score 2 · Accepted Answer

はい、コード自体ではなく、削除されたコードにコメントすることをお勧めします。

この立場をさらに明確にするために、何らかの形式のチェックインコメントを許可するソースコード管理システム (SCCS) を使用する必要があります。そこに、コードが削除された理由に関するコメントを配置する必要があります。SCCS は、何が削除されたかを含め、コードに何が起こったかの完全なコンテキスト履歴を提供します。チェックインコメントを追加することで、その履歴をさらに明確にします。

コードに直接コメントを追加すると、混乱が生じるだけです。

score 2 · Accepted Answer

最近のコンセンサス (ここでの他の議論から) は、コードを削除する必要があるというものです。

私は個人的にコードをコメントアウトし、日付または理由でタグ付けします. 古い/古く、ファイルを通過している場合は、それを取り除きます。バージョン管理は簡単に元に戻せますが、コメントを外すほど簡単ではありません...

score 2 · Accepted Answer

コードのバージョン管理を回避しようとしているようです。理論的には素晴らしいアイデアのように思えますが、実際には非常に混乱する可能性があります。

デバッグや他のテストの実行のためにコードをコメントアウトすることを強くお勧めしますが、最終決定が下されたら、ファイルから完全に削除してください!

適切なバージョン管理システムを導入すると、変更をコメントアウトする作業が煩雑であることがわかると思います。

score 2 · Accepted Answer

一般的に、私は非常にまばらにコメントする傾向があります。良いコードは、あまりコメントしなくても読みやすいものであるべきだと私は信じています。

また、コードをバージョン管理します。特定の行が特定の理由で変更されたかどうかを確認するために、過去 20 回のチェックインの差分を作成できると思います。しかし、それはほとんどの変更で私の時間の無駄になります。

だから私は自分のコードを賢くコメントしようとします。かなり明白な理由で一部のコードが削除されている場合は、わざわざ削除についてコメントするつもりはありません。ただし、コードの一部が微妙な理由で削除されている場合 (たとえば、現在別のスレッドで処理されている機能を実行した場合など)、コードをコメントアウトまたは削除し、理由のバナーコメントを追加します。

   // this is now handled by the heartbeat thread
   // m_data.resort(m_ascending);

または：

   // don't re-sort here, as it is now handled by the heartbeat thread

ちょうど先月、特定の問題を修正するために 1 年前に変更したコードに遭遇しましたが、その理由を説明するコメントを追加していませんでした。元のコードは次のとおりです。

   cutoff = m_previous_cutofftime;

そして、中断された状態を再開するときに正しいカットオフ時間を使用するように最初に修正されたコードを次に示します。

   cutoff = (!ok_during) ? m_previous_cutofftime : 0;

もちろん、別の無関係な問題が発生しました。これはたまたま同じコード行に触れ、この場合は元の状態に戻しました。そのため、新しい問題は修正されましたが、古い問題は突然再壊れました。ああ！

チェックインされたコードは次のようになります。

   // this works for overlong events but not resuming
// cutoff = m_previous_cutofftime;
   // this works for resuming but not overlong events
// cutoff = (!ok_during) ? m_previous_cutofftime : 0;
   // this works for both
   cutoff = (!resuming || !ok_during) ? m_previous_cutofftime : 0;

もちろん、YMMV。

score 1 · Accepted Answer

これは、コンパイラのヒント/警告がアドレス指定されないままになっているような「壊れた」ウィンドウの考え方の1つです。それはいつかあなたを傷つけ、チームのだらしさを助長します。

バージョン管理のチェックインコメントは、このコードが削除された理由/理由を追跡できます。開発者がメモを残さなかった場合は、それらを追跡して抑制します。

score 1 · Accepted Answer

コードを削除する場合。削除したことにコメントしないでください。これがソース管理の全体的な目的であり (ソース管理を使用していますか? そうですか?)、コメントがコードを乱雑にするだけです。

score 1 · Accepted Answer

私はそれがひどい提案であることを認めます。そのため、リビジョンのあるソース管理があります。2 つのリビジョン間で何が変更されたかを確認する必要がある場合は、2 つのリビジョンを比較します。

score 1 · Accepted Answer

コメントアウトされたコードで雑然としたコードを見るのは嫌いです。コードを削除し、削除された理由を示すコミットメッセージを書きます。ソース管理を使用していますね。

アクティブなコードにデッドコードを散らかさないでください。

score 1 · Accepted Answer

コンセンサスに私の声を追加します。コードが削除された理由についてのコメントは、コードではなくソース管理リポジトリに入れます。

score 1 · Accepted Answer

大きな変更の最中にあり、既存の機能を修正する必要がある場合、将来のコードをコメントアウトすることは妥当なことです。システム。

score 1 · Accepted Answer

ちょっとした逸話として、私は数年前、ソースコードのバージョン管理について何も知らなかった会社にいました (彼らは後でそのようなツールを手に入れました...)。
そのため、私たちの C ソースには、「変更を加えるときは、プリプロセッサマクロで古いコードを無効にする」という規則がありました。

#ifdef OLD /* PL - 11/10/1989 */
void Buggy()
{
// ...
}
#else
void Good()
{
// ...
}
#end

言うまでもなく、私たちの情報源はすぐに読めなくなりました! 維持するのは悪夢でした...
そのため、ネストされた #ifdef / #else / #end などの間をジャンプする機能を SciTE に追加しました...もっと通常のケースではまだ役に立ちます。
後で、VCS を取得したら、古いコードを喜んで取り除くために Visual Studio マクロを作成しました。

さて、buti-oxa のように、コードを削除した理由を示す必要があると感じることがありました。同じ理由で、または不要になったと思われる古いコードを削除したためですが、よくわかりません（レガシー、レガシー...）。明らかに、すべての場合ではありません！
実際、私はそのようなコメントを残しませんが、その必要性は理解できます。
さらに悪いことに、あるバージョンでコメントアウトし、次のバージョンですべてを削除します...
現在の仕事では、重要なローカル変更のために古いコードを残しますが、緊急の場合にプロパティで再アクティブ化できます. 本番環境でしばらくテストした後、最終的に古いコードを削除します。

もちろん、VCS コメントは最良のオプションですが、変更が他の変更を含む大きなファイルの数行である場合、小さな削除を参照するのは難しい場合があります...

score 0 · Accepted Answer

一般的な「クリーンコード」の実践では、削除されたコードをコメントアウトしたままにしておくべきではありません。

私は原則に同意しますが、それがすべての開発状況に受け入れられるアプローチだとは思いません。私の経験では、コードのすべての変更とすべてのチェックインを追跡している人はほとんどいません。その結果、コメントアウトされたコードがない場合、そのコードが存在していたことに気付かない可能性があります。

そのようなコードをコメントアウトすることは、それが削除されようとしているという一般的な警告を提供する方法かもしれませんが、もちろん、関係者がその警告を見るという保証はありません (ただし、彼らがそのファイルを頻繁に操作する場合、彼らは見てください）。

個人的には、正しいアプローチは、そのコードを別のプライベートメソッドに分解し、関連する利害関係者に連絡して、保留中の削除を通知してから実際に関数を削除することだと考えています。

score 0 · Accepted Answer

私もそれはひどい提案だと思います:)

ソース管理を使用する必要があります。一部のコードを削除する場合は、コミット時にコメントを追加できます。したがって、必要に応じてコード履歴を保持できます...

score 0 · Accepted Answer

いつ古いコードにフォールバックしなければならないかわからないので、使用されていないコードにコメントします。古いコードは、当時より単純であった場合、他の人が理解するのに役立つかもしれません。

score 0 · Accepted Answer

アンドリューに同意します。IMO これが、バージョン管理を使用する理由です。適切なチェックイン/コミットコメントと差分ツールを使用すると、行が削除された理由をいつでも確認できます。

score 0 · Accepted Answer

任意の形式のソース管理を使用している場合、このアプローチは多少冗長です (説明的なログメッセージが使用されている限り)。

score 0 · Accepted Answer

私がいるところでは、1 つのリリースサイクルで古いコードをコメントアウトし、その後コメントを削除します。(これにより、新しいコードの一部に問題があり、古いコードに置き換える必要がある場合に、迅速に修正することができます。)

score 0 · Accepted Answer

ほとんどの場合、もちろん古いコードは削除して RCS で追跡する必要があります。

ただし、すべてのことと同様に、「削除されたすべてのコードは常に削除される」というステートメントを作成することは、間違ったアプローチだと思います。

さまざまな理由から、古いコードを残しておきたい場合があります。コードを残す主な理由は、将来そのコードのセクションで作業する開発者に古いコードを見てもらいたい場合です。

ソース追跡に依存しても、明らかにこれは得られません。

したがって、正しい答えは次のとおりだと思います。

-コード内の次の開発者が必要とする重要な情報を提供しない限り、古いコードを削除します。つまり、99% の確率で削除しますが、必要なドキュメントを次の開発者に提供する能力を、状況が許すときに削除するような厳格なルールを作成しないでください。

comments - 削除されたコメント コード

28 に答える 28

Related

Reference

comments - 削除されたコメントコード