高回転環境ではより多くのコメントが優れていますか？

今日は同僚と話していました。2つの異なるプロジェクトのコードに取り組んでいます。私の場合、自分のコードに取り組んでいるのは私だけです。彼女の場合、複数の人が同じコードベースで作業します。これには、かなり定期的に（8〜12か月ごとに）出入りする生協学生も含まれます。彼女は自分のコメントに寛大であり、あちこちにそれらを置いていると言った。彼女の推論は、コードの大部分が彼女によって書かれておらず、彼女以外の誰かによって変更される可能性があるため、物事がどこにあり、何をしているのかを思い出すのに役立つということです。その間、私はコード内のコメントを最小限に抑え、明白でない回避策またはバグがある場所にのみコメントを配置しようとします。ただし、コード全体をよりよく理解し、コードをより直接制御できます。

そのコメントでの私の意見は最小限であり、コードはストーリーの大部分を伝えるべきですが、彼女の推論も理にかなっています。彼女の推論に欠陥はありますか？コードが乱雑になる場合がありますが、短期から中期に多くの人が作業している場合、最終的には非常に役立ちます。

コメントによってコードが乱雑になることはありません。

そして、そうすると、まともなIDEごとにコメントを隠したり折りたたんだりできます。ストーリーは、コメントではなく、コード、要件ドキュメント、コミット履歴、ユニットテストで伝えることが理想的です。ただし、過度のコメントは、コメントが理由ではなく方法に集中している場合にのみ害を及ぼす可能性がありますが、それは別の議論です。

あなたとあなたの同僚はどちらも「正しい」と思いますが、違いはもちろん、あなたが一人で仕事をしていることと、彼女がチームで働いていることです。コメントに関してそれほど哲学はありませんが、コードの伝達に関する要件は大きく異なります。「覚えやすい」という議論は、彼女があなたよりもはるかに多くのコードを扱い、さらに重要なのは、それぞれが個人的な好みや癖を持っているさまざまな人によって生成されたコードから生じる可能性があります。

結局のところ、コードコメントは、明らかな欠陥ではありますが、コードを伝える最も簡単で迅速な方法です。チームの構成と組織によっては、それが最小公分母に適用される唯一の方法である場合もあります。私は通常、一人で仕事をしているとき、そしてチームで仕事をしているときに同僚の意見に順応するとき、特にバランスの取れていないチームのスキルの場合、あなたのコメントの哲学に従います。

そのような環境での多くのコメントは、別の方法で解決されるべき問題を隠蔽しています。

高品質で読み取り可能なコードは、その機能を説明するために追加のコメントを必要としません。コメントするのは、特定の方法で何かが行われた理由を説明したいときだけです。そして、それでも、それらのコメントは、おそらくソース管理のコミットメッセージに含まれている可能性があります。

そのため、彼女が解決しようとしている問題は、読みやすい方法でコードを書く方法がわからない学生と協力しなければならないことです。私の意見では、コメントでコードを乱雑にすることは、その問題に対する弱い解決策です。

厳格なコードレビューは、コードの整理と、同じ会社であろうと他の場所であろうと将来の生徒の改善の両方において、はるかに効果的です。

コメントの問題は、コメントとの同期が非常に速くなる傾向があることです。これは、コード内に誤解を招く、または完全に間違ったコメントが含まれることが多いことを意味します。

目標は、コードベースを簡単に理解して変更できるようにすることです。コメントを自由に使用することでこれを行うことができます（ただし、データコメントから問題が発生する可能性があります）。 「質問。どちらのアプローチでもうまくいくかもしれませんが、コードを変更するには、コメントだけでなくコード自体を理解する必要があります。したがって、コメントはコードの理解に役立つかもしれませんが、結局のところ、おそらくコード自体を理解する必要があります。とはいえ、私は自己文書化コードのアプローチを好みます。クリーンなコードベースを作成するより直接的な方法のようです。

「高回転環境でより多くのコメントが得られますか？」

私は彼らがもっと悪いかもしれないと思う：

• 作成者が異なれば、スタイルや詳細のレベルも異なり、他の人によるコメントの更新が少なくなります。

• 「コメントが必要なもの」の意見は人によって異なります。

• わかりやすい名前のコードを読みやすくするのではなく、コメントで読みにくいコードを記述する習慣を続けています。

• 形式と一貫性を維持すること自体が仕事になります。

• 新規ユーザーは、迅速な変更を行う前に「フォーマット」標準を学習する必要があります。

ポイント1：売上高の高い環境では明瞭さが重要

ポイント2：冗長性は明瞭ではない

コードにコメントを追加しても、明瞭さが改善される場合とされない場合があります。追加するコメントによって異なります。そして、最適な透明度に到達すると、コメントを追加することで状況が悪化し、良くなることはありません。

コメントは明確なコンポーネントですが、コード品質は非常に重要なコンポーネントです。賢さは明快さの反対です。カジュアルな読み物でコードの機能がすぐに明らかにならない場合、コードは特に明確ではなく、コメントは（コメントがどれほど高品質であっても）明確なコードの貧弱で効果のない代替物です。

たとえば、特定の状況では関連のないフィールドの上位ビットにフラグを詰めることは完全に許容される場合があり、特定の状況ではパフォーマンスの観点から意味のあることになるかもしれませんが、明確さに関しては常に悪い考えです、それから地獄をコメントアウトしても。

コードの実行内容を散文で説明する必要がある場合は、次のいずれかを検討してください。これらの一部はパフォーマンスに影響を与える可能性がありますが、特定のケースではパフォーマンスは明快さほど重要ではないことに注意してください。

• より良い変数名と関数名
• より良いコードレイアウトと間隔
• 良いアイデアだと思った「トリック」を削除します
• 概念的な機能に応じてコードをグループ化します（たとえば、一度だけ呼び出した場合でも、特定の目的のコードを適切な名前の機能に抽出します）
• より単純なアルゴリズムを使用する（条件が許す場合）
• 一般的な機能によく知られているライブラリを使用する

単純化された答え：「コードが読み直される可能性が高いほど、何をしているのかを説明する負担が大きくなります。」これは...スタイルの基準に従うことで、正式な文書を作成することによって、それをコメント化し、読みやすいコードを作成することにより、それができることに注意してください可能性があります、それはAにも、確かに他人の事実だが、後で再読み込みを行っていること離職率の高い環境。

コメントがドキュメンテーションであるかどうかをカバーする別の素晴らしいスレッドがあります。

コメントは、他のシナリオよりもいくつかのシナリオで役立ちます。これは非常に基本的なことであるため、非常に多くの回答の中でそれを説明する方法を心配しているため、「反コメント」であると感じています。

コードが何年も読まれない場合、頻繁にコードのリファクタリング、強力なコード所有権、および大量のコードレビューがある場合よりもコメントの方が重要です。アプリケーションが複雑で、その言語に堪能なオブザーバーにすぐにはわからないテクニックを使用している場合、システムが栄光の「Hello World」である場合よりもコメントの方が重要です。コードベースが可能な限り標準に厳密ではない場合、コメントは 6層のQAで作業している場合よりも重要です。言語を習うだけの8人のチームで作業している場合、8人のプログラミングピュリッツァーがいる場合よりもコメントの方が重要です。ひび割れたアプリケーションがひざに落ちた場合、コメントは、最初からきれいに構築できた場合よりも重要です。

これらのシナリオのほとんどで、コメントの使用を増やすよりも根本的な原因を修正する方が良いでしょうか？絶対に。しかし、町のスマートフォンよりも指紋が多いコードベースにこだわる場合があります。それを改善する最善の方法は、変更をできるだけ読みやすくし、コメントをコメントアウトすることです。

あなたの特定の問題に対して：コメントがコードを乱雑にするほど散らばってはいけません。関数が存在する理由と、おそらくそのアプローチを使用する理由を説明する、サブルーチンの上部にあるよく書かれた段落は、次のプログラマーが方向を知るのに役立つ最善の策です。