コメントアウトされたコードは貴重なドキュメントになりますか？

次のコードを書きました。

if (boutique == null) {
    boutique = new Boutique();

    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.persist(boutique);
} else {
    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    //boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.merge(boutique);
}

ここにはコメントアウトされた行があります。しかし、私はそれが差が間にあるものを明らかにすることにより、コードが明確になり考えるifとelse。違いは、色の強調表示でさらに顕著です。

このようなコードをコメントアウトするのは良い考えでしょうか？

答えのほとんどは、この特定のケースをリファクタリングする方法に焦点を当てていますが、コメントアウトされたコードが通常悪いのはなぜかという一般的な答えを提供します。

まず、コメントアウトされたコードはコンパイルされません。これは明らかですが、次のことを意味します。

1. コードが機能しないこともあります。

2. コメントの依存関係が変更されても、明らかに壊れることはありません。

コメントされたコードは非常に「デッドコード」です。長く座っているほど腐り、次の開発者に提供する価値はますます少なくなります。

第二に、目的は不明です。ランダムにコメント化された行がある理由のコンテキストを提供する長いコメントが本当に必要です。コメントされたコード行だけを見たとき、なぜそこにたどり着いたのかを理解するために、どうやってそこにたどり着いたのかを調べなければなりません。誰が書いたの？何をコミットしますか？コミットメッセージ/コンテキストは何でしたか？等。

代替案を検討してください：

• 目標が関数/ APIの使用例を提供することである場合は、単体テストを提供します。単体テストは実際のコードであり、正しくない場合は壊れます。
• コードの以前のバージョンを保持することが目的の場合は、ソース管理を使用します。以前のバージョンをチェックアウトし、コードベース全体でコメントを切り替えて変更を「元に戻す」ことをお勧めします。
• 目的が同じコードの代替バージョンを維持することである場合は、ソース管理を再度使用します。結局のところ、これがブランチの目的です。
• 目的が構造を明確にすることである場合は、コードを再構築してより明確にする方法を検討してください。他の回答のほとんどは、これを行う方法の良い例です。

このコードの最大の問題は、これらの6行を複製したことです。その重複を排除すると、そのコメントは役に立ちません。

boutiqueDao.mergeOrPersistメソッドを作成する場合、これを次のように書き換えることができます。

if (boutique == null) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

boutiqueDao.mergeOrPersist(boutique);

特定のオブジェクトを作成または更新するコードは一般的であるため、たとえばmergeOrPersistメソッドを作成するなどして、一度解決する必要があります。確かに、これら2つのケースのすべての割り当てコードを複製しないでください。

多くのORMは、何らかの方法でこれをサポートしています。たとえば、idがゼロの場合は新しい行を作成し、がゼロでidない場合は既存の行を更新します。正確な形式は、問題のORMに依存します。また、使用しているテクノロジーに詳しくないので、それを支援することはできません。

mergeOrPersistメソッドを作成したくない場合は、isNewBoutiqueフラグを導入するなど、他の方法で重複を排除する必要があります。それはきれいではないかもしれませんが、割り当てロジック全体を複製するよりもはるかに優れています。

bool isNewBoutique = boutique == null;
if (isNewBoutique) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

if (isNewBoutique)
    boutiqueDao.persist(boutique);
else
    boutiqueDao.merge(boutique);

これは絶対に恐ろしい考えです。意図が明確ではありません。開発者は誤って行をコメントアウトしましたか？何かをテストするには？どうしたの？！

どちらの場合もまったく等しい6行が表示されるという事実は別として。むしろ、このコードの重複を防ぐ必要があります。その後、ある場合にはsetSelectedを追加で呼び出すことがより明確になります。

いいえ、それはひどい考えです。そのコードに基づいて、次の考えが思い浮かびます。

• 開発者がデバッグしていたため、この行を以前の状態に戻すのを忘れていたため、この行はコメント化されています
• この行は、かつてはビジネスロジックの一部だったためコメントアウトされていますが、もはやそうではありません
• この行は、本番環境でパフォーマンスの問題を引き起こし、開発者は本番システムにどのような影響があるのか​​を確認したいため、コメント化されています

数千行のコメントアウトされたコードを見た後、私はそれを見たときに唯一の賢明なことをしています：すぐにそれを削除します。

コメントアウトされたコードをリポジトリにチェックインする合理的な理由はありません。

また、コードは多くの重複を使用します。できるだけ早く人間が読みやすいように最適化することをお勧めします。

CodesInChaosの答えに追加したいのは、それをさらに小さなメソッドにリファクタリングできることを指摘することです。構成によって共通の機能を共有すると、条件が回避されます。

function fill(boutique) {    
  boutique.setSite(site);
  boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
  boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
  boutique.setNom(fluxBoutique.getNom());
  boutique.setIdWebSC(fluxBoutique.getId());
  boutique.setDateModification(new Date());
}    

function create() {
  boutique = new Boutique();      
  fill(boutique);
  boutique.setSelected(false);
  return boutiqueDao.persist(boutique);
}

function update(boutique) {
  fill(boutiquie);
  return boutiquieDao.merge(boutique); 
}

function createOrUpdate(boutique) {
  if (boutique == null) {
    return create();
  }
  return update(boutique);  
}

これは明らかにコメントアウトされたコードの良いケースではありませんが、私はそれを正当化すると思う状況があります：

// The following code is obvious but does not work because of <x>
// <offending code>
<uglier answer that actually does work>

明らかな改善はそうではないというのは、後でそれを見る人への警告です。

編集：私は小さなことについて話している。大きい場合は、代わりに説明します。

この特定の例では、主にDibkkeの回答で概説されている理由により、コメントアウトされたコードは非常に曖昧です。他の人は、これを行う誘惑さえ避けるためにコードをリファクタリングする方法を提案していますが、何らかの理由でそれが不可能な場合（たとえば、行が似ていますが、十分に近くない）、私は次のようなコメントを歓迎します：

//このブティックの選択を解除する必要はありません。[何でも]

ただし、コードを残したり（コメントアウトしたり）コードを非難できない状況もあると思います。MATLABやNumPYなどを使用する場合、多くの場合、1）配列を反復処理して一度に1つの要素を処理するか、2）配列全体を一度に操作する同等のコードを記述できます。場合によっては、後者のほうがはるかに高速ですが、読むのがはるかに困難です。一部のコードをベクトル化された同等のコードに置き換える場合、次のように元のコードを近くのコメントに埋め込みます。

%%以下のベクトル化されたコードはこれを行います。

% for ii in 1:N
%    for jj in 1:N
%      etc.

％ただし、マトリックスバージョンは標準入力で最大15倍高速に実行されます（MK、2013年3月10日）

明らかに、2つのバージョンが実際に同じことを行い、コメントが実際のコードと同期したままになるか、コードが変更された場合に削除されるように注意する必要があります。明らかに、時期尚早な最適化に関する通常の警告も適用されます...

有用なコメントアウトされたコードを見たのは、すべてのオプションのコードが提供されている設定ファイルでしたが、コメントアウトされているため、コメントマーカーを削除するだけで簡単に設定を有効にできます。

## Enable support for mouse input:
# enable_mouse = true

この場合、コメント化されたコードは、利用可能なすべてのオプションとその使用方法を文書化するのに役立ちます。全体を通してデフォルト値を使用することも慣習的であるため、コードはデフォルト設定も文書化します。

一般的に、コードはコードを書いた人にのみ自己文書化されます。ドキュメントが必要な場合は、ドキュメントを書きます。ソースコードベースを初めて使用する開発者が何千行ものコードを読んで、何が起きているのかを把握しようとすることは期待できません。

この場合、コメントアウトされたコード行の目的は、重複するコードの2つのインスタンスの違いを示すことです。コメントを使用して違いを微妙に文書化する代わりに、コードが書き直されるようにしてください。次に、コードにコメントする必要があると感じたら、適切なコメントを書きます。

いいえ、コメントされたコードは古くなり、価値のないものよりもすぐに悪くなります。現在のすべての仮定とともに、実装のいくつかの側面を固めるため、多くの場合有害です。

コメントには、インターフェイスの詳細と目的の機能を含める必要があります。「意図された機能」：最初にこれを試み、次にそれを試み、次にこのように失敗することを含めることができます。

私が見たプログラマーは、コメントに物事を残そうとしているので、完成した製品に何かを追加していなくても、自分が書いたものに夢中です。

非常にまれなケースである可能性がありますが、あなたがやったようにではありません。他の答えは、その理由をかなりうまくまとめています。

まれなケースの1つは、すべての新しいパッケージの開始点として、主に重要なものが残されていないことを確認するために、ショップで使用するテンプレートRPM仕様です。すべてではありませんが、ほとんどのパッケージには、標準名を持ち、タグで指定されたソースを含むtarballがあります。

Name:           foomatic
Version:        3.14
 ...
Source0:        %{name}-%{version}.tar.gz

ソースのないパッケージの場合、標準形式を維持するためにタグをコメントアウトし、その上に別のコメントを追加し、開発プロセスの一部として誰かが問題を止めて考えたことを示します。

Name:           barmatic
Version:        2.71
 ...
# This package has no sources.
# Source0:        %{name}-%{version}.tar.gz

他の人がカバーしているように、そこに属するものと間違われる可能性があるため、使用されないことがわかっているコードを追加しないでください。できる。ただし、コードの欠落が予想される理由を説明するコメントを追加すると便利です。

if ( condition ) {
  foo();
  // Under most other circumstances, we would do a bar() here, but
  // we can't because the quux isn't activated yet.  We might call
  // bletch() later to rectify the situation.
  baz();
}

コメントアウトされたコードはアプリケーションによって使用されないため、使用されない理由を示すコメントを追加する必要があります。ただし、そのコンテキスト内では、コメントアウトされたコードが役立つ場合があります。

私が思い浮かぶのは、一般的で魅力的なアプローチを使用して問題を解決する場合ですが、実際の問題の要件はその問題とわずかに異なることがわかります。特に、要件がかなり多くのコードを必要とすることが判明した場合、メンテナーが古いアプローチを使用してコードを「最適化」する誘惑は強いと思われますが、それを行うとバグが元に戻ります。コメントで「間違った」実装を維持することは、この状況でそのアプローチが間違っている理由を正確に説明するために使用できるため、これを解消するのに役立ちます。

これは非常に頻繁に発生することを想像できる状況ではありません。通常、サンプルの「間違った」実装を含めずに物事を説明すれば十分です。しかし、それだけでは不十分な場合を想像できます。そのため、質問はそれが有用であるかどうかに関するものなので、そうです。ほとんどの場合ではありません。

これは相性が良くありません。

コメントされたコードは...ただのコードではありません。コードはロジックの実装用です。コード自体を読みやすくすることは芸術です。@CodesInChaosがすでに示唆しているように、コードの繰り返し行はロジックの実装としてはあまり良くありません。

真のプログラマーは論理的な実装よりも読みやすさを好むと本当に思いますか？（ちなみに、論理表現に入れるコメントと「補数」があります）。

私の知る限り、コンパイラ用のコードを書く必要があります-それがいいのです-「それ」がそのコードを理解していれば。人間が読みやすいように、コメントは、開発者（長期的に）、そのコードを再利用する人々（テスターなど）に適しています。

そうでなければ、ここでもっと柔軟な何かを試すことができます。

boutique.setSite（site）は次のように置き換えることができます

setsiteof.boutique（site）。OOPには、読みやすさを向上させるさまざまな側面と視点があります。

このコードは最初は非常に魅力的であるように見えますが、人間が読みやすい方法を見つけた一方で、コンパイラーも完璧に機能していると考えることができます。時間の経過とともにさらに複雑になります。