時代遅れのコメントは都市の神話ですか？

「コメントは時代遅れになりがちだ」と​​いう主張をする人は常にいます。事は、私は私のキャリア全体で2つまたは3つの時代遅れのコメントを見たことがあると思います。別々のドキュメントの古い情報は常に発生しますが、私の経験では、コード自体の古いコメントは非常にまれです。

誰と仕事をしているのか幸運だったのですか？特定の産業は他の産業よりもこの問題を起こしやすいですか？あなたはありますか特定のあなたが見てきた最近の時代遅れのコメントの例は？それとも、時代遅れのコメントは実際の問題よりも理論的な問題ですか？

常に

時代遅れで誤解を招くコメントで泳いでいるのは私だけではないと本当に信じられません。偶然に、これは理解を助ける：

おそらく最も重要なのは、コードの年齢です。次の要因は、スタッフの離職率です。

私は同等の研究開発と保守作業をしています。R＆Dは新しいコードであり、一般的にはbeat地から少し外れています。私の同僚の多くは、まだライブラリーが存在しないものを試すときに、多くのコメント付きの説明を入れることを信じています。コードに対するコメントの比率は通常よりも高いため、物事が同期しなくなる可能性が高くなります。

メンテナンスコード...私は、10年以上前のシステムと5年以上前のシステムのアクティブメンテナーです。10年前のコードとコメントは、ご想像のとおり、ひどいものです。10年以上にわたって、あなたはコードベースに多くの手を携え、全体がどのように機能するのか誰にもわかりません。チームの離職率が非常に低いため、5年前のコードとコメントは非常に優れています。

私の製品も特定の顧客向けに高度にカスタマイズされています。

具体例：

• インメモリコピーの回避など、特定の方法論のパフォーマンスの改善を説明するコメント。大容量のRAMを搭載したPentium 2のトップエンドマシンの場合は大した問題ではありませんが、現在はほとんど問題ありません。

• TODO

• コメントを含むコピーアンドペーストされたコードのブロック。コメントは元の場所で意味を成したかもしれませんが、ここではほとんど意味がありません

• コメントアウトされたコードの上にコメントブロックがあります（何年経っているのかを知っている人）。

これらすべてにおいて、ソフトウェアと同じレベルでコメントとコードを維持しない傾向が見られます。IDEと基本的な開発者の習慣はこれを助けません。私の目はそれらを追い越すように訓練されています。グリーンフィールドやアクティブなプロジェクトでは、コメントの古さを避けるのは比較的安いと思います。コード/コメントの比率を高く保つことができれば、それらを最新に保つことは大したことではありません。実稼働システムでのバグ修正のためにx時間予算を組んでいる場合、これらのことを追い詰めるのを正当化するのは少し難しくなります。

「コメントは時代遅れになる傾向があります。」

これが問題になる可能性があることを知るのに十分な頻度でこれが起こるのを見てきました。

事は、私は私のキャリア全体で2つまたは3つの時代遅れのコメントを見たことがあると思います。

誰もがコメントを十分に管理し、維持する環境で働くことは完全に可能であるべきだと思います。編集中のコードの近くにあるコメントを見て、必要に応じて更新するのはほんの少しの余分な努力です。コメントがあまりにも遠すぎてすぐに気付かない場合は、とにかく悪いコメントであり、そもそも（少なくともそこには）追加すべきではありません。

さらに、通常、コメントは古くなる傾向があるという声明とともに、読みやすさを低下させ、人々を混乱させるという声明に従います。これは私がまだ経験していないことです。古いコメントに出会うたびに、何が変わったのかがはっきりとわかり、それに応じてコメントを更新して、新しいコードを表すようにします。

Roehmらによる最近の研究。2012年は次のことを遵守しています。

[28人中]の21人の参加者は、ソースコードとインラインコメントから主要な情報を得ていると報告しましたが、ドキュメントが主要な情報源であると述べたのは4人だけでした。

これは、コード自体のコメントは一般に依然として非常に有用であると考えられるというあなたの疑念に沿っています。これは、古いドキュメントと古いコメントの間に明確な線を引くべきであることを示しています。

_{Roehm、T.、Tiarks、R.、Koschke、R。、およびMaalej、W。（2012年6月）。プロの開発者はソフトウェアをどのように理解しますか？ソフトウェア工学に関する2012年国際会議の議事録（pp。255-265）。IEEEプレス。}

時代遅れのコメントは仕事の匂いです。それは、古くなった、または無視された単体テストを持っているようなものです。これは、かつてショップでアクティブだった優れたプロセスがカウボーイコーディングに退化していることを示しています。物事を適切に行うために時間をかけるという適切な「エンジニアリング文化」が崩壊しました。プロジェクト/会社はおそらく技術的な負債を抱えています。

要するに、はい、あなたは幸運でした。あなたのキャリアの中でこれまでに合理的にうまく運営されている一連の店を偶然持っていた場合、これを見ないことはかなり可能です。しかし、より典型的な、あまりうまく運営されていない店では、これは他の混乱と並行して行われます。

コメントはテストのようなものです。コメントは最新の状態では非常に優れていますが、コードがないとコードを理解しにくくなります。

時代遅れのコメントを見たことがないなら、あなたはとても幸運だった。

私が扱ってきたほとんどのコードベースは時代遅れのコメントで一杯であり、通常はヘルプではなく混乱の原因であるため、通常はコメントを完全に無視します。

古いコメントはJavaDocに頻繁に表示されます。

• 存在しない引数のリスト
• すべての引数を説明していない（欠落している引数はおそらく後で追加された）
• 例外などについても同様です

さらに、パフォーマンスに関するほとんどの考慮事項がコード自体よりも早く失効する傾向がある場合、「パフォーマンスのためにこれを行う」などのコメントがコメントに記載されることがあります。

私は時々古いコメントに対処します。それは確かに都市の神話ではありません。人々が最悪の慣行のリストでそれを言及するのは、それがあなたに非常に頻繁に当たるからではなく、それが起こると、通常あなたに多くの時間と労力がかかるからです。

コードベースでは、ほとんどの古いコメントは、メソッド宣言の近くではなく、呼び出しの近くでメソッドの動作を記述する（アンチ）パターンの使用が原因です。誰かが長いコードをメソッドに抽出し、そのメソッドがその時点で一度だけ呼び出されてから、メソッド呼び出しをコメントするときに発生します。したがって、次のような結果になります。

featureList = GetFeatures();

// Sorting features and deleting empty ones from the list...
ProcessFeatures(featureList);

そして、メソッドはコメントなしで以下のどこかに宣言されています。人々はこれらのメソッドを長年にわたって仕様の変更に対処し、バグを修正し、最終的にはリストをソートせず、空の機能が見つかったときに例外をスローするメソッドになります。したがって、上記のコメントは古いコメントであり、最終的にはデバッガーで時間がかかります。これらはいくつかのコードベースで起こります。

これを自問してください。関連するコメントを変更したり、新しいコメントを追加したりせずに、コード行を変更したことがありますか？

私は多くのレガシーコードを使用してきましたが、コメントが関連性に欠けることもあります。

ほとんどの場合、私の経験はあなたの経験と一致しますが、コードベース全体に当てはまる場合があります。数年前にコンサルティングショップによって作成されたアプリであり、クライアントとは「良好な状態」ではなくなりました。

同社はコードにコメントして例外的な仕事をしましたが、元のハンドオフ以来それを維持していたプログラマーは、「絶対に変更する必要があるものだけを変更する」という考え方の一部でした。あいにく、彼らはコメントに対しても同じ態度を維持し、コメントとコードとの間に大きな隔たりが生じました。

古くなった説明的なコメントはあまり多くありませんが、何年もそこにあったTODOコメントがたくさんあります。私は彼らがタイムカプセルのようであり、このようなことを言っていたらいいのに。

//TODO: In 15 years AND NO SOONER... actually implement this method.

私が取り組んだ最後の3つのプロジェクトは、コードベースから古く、誤解を招く、無意味なコメントを削除するのにそれぞれ数日を費やしました。可能かつ必要な場合は、より適切なコメントに置き換えますが、多くの場合、コメントを削除して先に進むだけの問題です。

私は他の人から引き継いだほとんどすべてのコードベースで同じことをしました。通常はしばらくメンテナンスされておらず、元の所有者が長い間行っていた、および/または適切なハンドオーバーを行うことを望んでいない、または不可能だった後です。

コメントの使用が減少している可能性があります。誰のコードがどれだけ適格ですか？1つには、誰かが実際にコメントを古くする必要があります。次に、コメントされたコードを変更する必要があります。高い割合のコードが適格かどうかはわかりません。

1つの悪いコメントだけに頼って、アプリケーションの大部分を台無しにし、多くの時間を浪費する必要があります。

大量のコードを大量に生成する組織では、コメントの同期を保つことは困難です。何が起こっているのかを理解する最良の方法は、作業中のモジュールの制御フロー図を描くソフトウェアを使用することです。それが、ソフトウェアが何をするのかを把握し続ける唯一の方法です。