古いコメントは都会の神話ですか？
「コメントは古くなる傾向がある」という主張をしている人がよくいます。問題は、私のキャリア全体で2、3の古いコメントを見たことがあると思います。別のドキュメントの古い情報は常に発生しますが、私の経験では、コード自体の古いコメントは非常にまれです。
一緒に仕事をしている人に幸運でしたか？特定の業界が他の業界よりもこの問題を起こしやすいですか？ 特定最近見た古いコメントの例はありますか？または、古いコメントは実際の問題よりも理論的な問題のほうが多いですか？
常に
時代遅れで誤解を招くコメントで泳いでいるのは私だけでは本当に信じられません。オフチャンスでは、これは理解に役立ちます：
それはおそらく最も重要なことに、コードの古さに依存しています。次の要因は、スタッフの離職率です。
私は同等の部品の研究開発とメンテナンス作業を行っています。 R＆Dは新しいコードであり、一般的には打開策から少し外れたものです。私の同僚の多くは、すでにライブラリが存在しないものを試すときに、コメント付きの説明をたくさん入れると信じています。コメントとコードの比率は通常よりも高いため、同期が取れなくなる可能性が高まります。
メンテナンスコード...私は10年以上前のシステムと5年以上前のシステムのアクティブなメンテナーです。10年前のコードとコメントは、ご想像のとおり、ひどいものです。 10年以上にわたり、コードベースに多くの手を携えており、全体がどのように機能するかについて誰も理解していません。 5年前のコードとコメントは、チームの離職率がかなり低いため、かなり良いものです。
私はほとんどすべてのサービスに従事していますが、当社の製品も特定の顧客向けに高度にカスタマイズされています。
具体的な例：
インメモリコピーの回避など、特定の方法論のパフォーマンス向上を説明するコメント。 MBのRAMを搭載したPentium 2のトップエンドマシンでは大きな問題ですが、現在はほとんど問題になりません。
TODO
コメントを含むコピー貼り付けされたコードのブロック。コメントは元の場所では意味があったかもしれませんが、ここではほとんど意味がありません
コメントアウトされたコードの上にコメントブロック（そこに何年あるか知っている人）。
これらすべてにおいて、コメントとコードをソフトウェアと同じレベルに維持しないという傾向が見られます。 IDEと基本的な開発者の習慣はこれに役立ちません。私の目はそれらを追い越すように訓練されています。グリーンフィールドやアクティブなプロジェクトでは、コメントの古さを回避するのは比較的安価です。コード/コメントの比率を高く保つことができれば、それらを最新に保つことは大したことではありません。本番システムのバグ修正のためにx時間の予算が割り当てられている場合、これらのものを追い詰めるのを正当化するのは少し難しいです。
「コメントは古くなる傾向があります。」
これが問題になる可能性があることを知るのに十分な頻度でこれが発生するのを見てきました。
問題は、私のキャリア全体で2、3の古いコメントを見たことがあると思います。
誰もがコメントに十分気を配り、維持する環境で働くことが完全に可能であるべきだと私は信じています。編集しているコードの近くのコメントを見て、必要に応じてコメントを更新するのは、ほんの少しの追加作業です。コメントが離れすぎてすぐに気付かない場合は、とにかく悪いコメントであり、最初に（または少なくともそこに）追加されるべきではありませんでした。
さらに、通常はコメントが古くなる傾向があるという声明とともに、これは読みやすさが低下し人々を混乱させるという声明に従います。これは私がまだ経験したことがないものです。古くなったコメントに遭遇するたびに、何が変わったのかをはっきりと確認し、それに応じてコメントを更新して、新しいコードを表すようにします。
Roehm et al。2012 による最近の研究では、次のことが観察されています。
21人の参加者（28人中）は、ソースコードとインラインコメントから主要な情報を取得していると報告しましたが、ドキュメントが主要な情報源であると述べたのは4人だけです。
これは、コード自体のコメントは一般に依然として非常に有用であると考えられているというあなたの疑念と一致しています。これは、古いドキュメントと古いコメントの間に明確な線を引く必要があることを示しています。
Roehm、T.、Tiarks、R.、Koschke、R.＆Maalej、W.（2012年6月）。 プロの開発者はソフトウェアをどのように理解しますか？ 2012年ソフトウェア工学国際会議の議事録（pp。255-265）。 IEEE Press。
古いコメントは仕事の匂いです。これは、ユニットテストを古くしたり無視したりするようなものです。これは、かつてショップでアクティブだった優れたプロセスがカウボーイコーディングに退化していることを示しています。時間をかけて物事を適切に行う適切な「エンジニアリング文化」が崩壊しました。プロジェクト/会社はおそらく技術的負債に陥っています。
要するに、はい、あなたは幸運でした。キャリアの中でこれまでに合理的に運営されている一連のショップをたまたま持っている場合、これほど多くを目にすることはないでしょう。しかし、より一般的な、あまり運営されていないショップでは、これは他のカオスと並行して実行されます。
コメントはテストのようなもので、最新の場合は非常に優れていますが、ない場合はコードの理解がさらに難しくなる可能性があります。
古くなったコメントを見たことがないなら、あなたはとても幸運でした。
私が扱ったほとんどのコードベースは古くなったコメントでいっぱいであり、コメントは通常ヘルプではなく混乱の原因となるため、通常は完全に無視します。
古くなったコメントがJavaDocに表示されることがよくあります。
- 存在しない引数のリスト
- すべての引数を説明していない（不足している引数はおそらく後で追加された）
- 例外などの同様のもの.
さらに、ほとんどのパフォーマンスの考慮事項がコード自体よりも古くなりがちである場合、コメントには「パフォーマンスのためにここでこれを行う」などと記載されることがあります。
私は時々古いコメントを扱います。それは確かに都市の神話ではありません。最悪の習慣のリストで人々がそれを言及するのは、それがあなたに頻繁に当たるからではなく、それが出たとき、それは通常あなたに多くの時間と労力を費やすからです。
私たちのコードベースでは、ほとんどの古いコメントは、メソッドの宣言の近くではなく、呼び出しの近くでメソッドの動作を記述する（アンチ）パターンの使用が原因です。これは、誰かが長いコードをメソッドに抽出するときに発生します。このメソッドは、現時点では一度しか呼び出されず、メソッド呼び出しにコメントを付けます。つまり、次のような結果になります。
featureList = GetFeatures();
// Sorting features and deleting empty ones from the list...
ProcessFeatures(featureList);
そして、メソッドはコメントなしで以下のどこかで宣言されています。人々は何年にもわたって、仕様の変更やバグの修正を扱ってこれらのメソッドを混乱させ、最終的にはリストをソートせず、空の機能を見つけると例外をスローするメソッドになってしまいます。したがって、上記のコメントは古くなったコメントであり、最終的にはデバッガで時間がかかります。これらは一部のコードベースで発生します。
自問してみてください。コード行を変更し、関連するコメントを変更したり、新しいコメントを追加したことはありますか？
私は多くのレガシーコードを扱ってきたので、コメントが関連性が低い場合さえあります。
私が取り組んだ最後の3つのプロジェクトは、コードベースから古い、誤解を招く、そしてまったく役に立たないコメントを削除するのに数日を費やしました。可能な場合は必要に応じて、より適切なコメントに置き換えますが、多くの場合、コメントを削除して次に進むだけの問題です。
私は他の人から引き継いだほとんどすべてのコードベースで同じことを行いました。通常、しばらくメンテナンスされておらず、元の所有者が長くいなくなっているか、適切なハンドオーバーを実行したくない、または実行できなくなった後です。
ほとんどの場合、私の経験はあなたの経験と一致しますが、コードベース全体に当てはまるケースに遭遇しました。それは、クライアントと「仲良く」されなくなったコンサルティングショップによって何年も前に書かれていたアプリでした。
同社はコードにコメントするという並外れた仕事をしましたが、元のハンドオフ以来それを維持していたプログラマーは、それ自体は悪くない「絶対に変更する必要があるものだけを変更する」考え方の一部でした。残念ながら、彼らはコメントに対しても同じ態度を保ち、時間が経つにつれてコメントとコードの間にかなり大きな分離が生じました。
古くなった説明コメントはあまり多くありませんが、何年にもわたって行われているTODOコメントはたくさんあります。私はそれらがタイムカプセルのようであり、次のように言っていればいいのに：
//TODO: In 15 years AND NO SOONER... actually implement this method.
コメントの使用が減少している可能性があります。誰かのコードのどれだけが適格ですか？一つには、誰かが実際にそれらが古くなるためにコメントを含める必要があります。次に、コメントされたコードを変更する必要があります。高い割合のコードが適格かどうかはわかりません。
アプリケーションの大きな部分を台無しにし、多くの時間を浪費するためには、1つの悪いコメントに頼る必要があります。
大量のコードを生成する組織では、コメントを同期させることは困難です。何が起こっているのかを理解する最良の方法は、作業中のモジュールの制御フロー図を描くソフトウェアを使用することです。それが、ソフトウェアが何をしているかを感じ続ける唯一の方法です。