コメントを使用する利点は何ですか
新しい仕事を受け入れたところです。私たちのアプリケーションは、50,000行のコード領域にあります。コメントはありません。アプリケーションの動作を理解するのが難しいと感じています。チームにコメントの使用を開始させることで、プロジェクトに参加する次の人のためにこれを防止したいと思います。
コメントをサポートするか、コードの重複を考慮するかを忘れてください。チームがコメントの使用を開始する理由として使用できるコメントを使用する利点のいくつかは何ですか。コメントを支持する議論はありますか（反対する議論を探していません）コメントを使用するとコードの品質が向上することを示す出版物や研究はありますか？
クリーンコード は、コメントが適切な場合とそうでない場合のコメントに関する章全体を備えています。また、それほど多くのコメントを必要としないコードを作成する方法に関する多くの実用的なアドバイス。
編集：アンナは要約を求めました、そしてあなたはプロコメントの理由だけを求めていたので、本からのコメントを使用する正当な理由の目次レベルの要約は以下を含みます：
- 著作権などの法的通知
- 関数名を使用して説明できない場合
- 決定の背後にあるあなたの意図
- ライブラリの呼び出し結果など、変更できないコードの明確化
- 結果の警告
- TODO（妥当な程度）
- 一見重要ではないものの重要性を増幅する
- パブリックAPIのJavadoc
これらの各トピックには2つ以上の段落があり、説明のために実際のコードサンプルが含まれています。それは本当に読む価値があります。
可能な限り、コードは自己記述的である必要があります。つまり、コメントなしで理解できるように十分に明確に記述する必要があります。これにより、他のユーザーがより保守しやすいコードが得られ、コメントが引き起こす冗長性が排除されます（コードを変更する場合は、コメントも更新する必要があります）。
ただし、コメントは、コードオブジェクトとシステムのさまざまな部分との関係、およびコードの適切な使用方法を記述した後の説明には重要です。つまり、アプリケーションまたはライブラリのすべての部分がどのように連携するかです。コメントをまったく書かないことを主張する開発者は、この点を十分に理解していないため、大きくて不透明で不可解なシステムを構築します。
ボブ・マーティンおじさんは、彼の著書「Clean Code」で、コメントを次の目的で使用することを提唱しています。
- 意図の説明
- 明確化
- 警告
- 増幅
- TODO
コメントには、少なくとも、各パブリックメンバーが行うこととその使用方法を説明し、すべてのパラメーターと戻り値について、それぞれの許容範囲（例：1〜1000）について説明する必要があります。
コードの一部を分析するとき、それが何であるかを知らない限り、それが正しいかどうかはわかりません想定。あなたはそれが何をするのかを知ることができるだけです。良いコメントは、コードが達成することになっていることをあなたに伝えることができます。冗長である場合、コードが目的を満たしていることを意味するため、これは良いことです。
コメントはあなたに伝えることもできますなぜそれはそれをします。
「128バイト未満の行を維持しました。それを超えると壊れるレガシーコンポーネントがあるためです」
「コメントの代わりに単体テストでそれを置く」と主張するかもしれない誰かは、それを単体テストでコメントする必要があることを理解できず、誰かが値を変更して回帰テストが失敗すると、彼は無駄だと気づくでしょう彼が見る必要があるコメントが間違った場所にあったので彼の時間。
これを提案しますか？
「write_but_do_not_exceed_the_limits_that_the_legacy_component_can_handle（）」
「良いネーミングで十分」は素朴で、そもそも適切にコメントする方法を学んだことのない怠惰な人々から生まれたアイデアです。
コメントは、アプリケーションの動作に関するものではなく、この関数がXを使用してその目的を達成する理由のためのものです。コードの記述が不十分で、コードの機能を説明する関数名がない場合は、各関数にそのための行を追加しますバンドエイドとしてコメントを使用する価値があるでしょう。コードのしくみがわからないとコードの読み方がわからないように聞こえます。コードが何をするかを意味する場合は、ユースケースやプロセスフロー、設計図などの外部ドキュメントで説明する必要があります。また、コードを間違った角度から学習しようとしているようです。コードが50000行の長さの単一の関数に含まれていない限り、長さは関係ありません。それだけで、コードの大きさにこだわります。大規模で複雑なシステムを部分的に学習し、レイヤー/クラスを選択して、プロジェクトとの関係でそれがどのように機能するかを学び、次にそれがどのように機能するかを学び、次に別のシステムを選択して繰り返します。また、低レベルの実装の詳細を学ぶ前に、アプリが実行する高レベルのフローを理解するのに役立つことも役立ちます。
追加されたコードにコメントの使用を強制しようとすることは、価値のある原因になる可能性がありますが、戻って既存のコードにコメントを追加しようとすることは無意味な努力です。その時点では、誰も開発者の考え方の中にいなかったため、なくなっています。
コメントの有用なポイント：
- Xを実行する方法がある理由を特定します。
- メソッドの入力/出力を特定して、パラメーターを微調整する必要があるかどうかを明確にします。ミリ秒または秒数で渡す場合、調整が必要な場合があります。
- メソッドの副作用を特定します。最初の意図以外に、知りたいことはありますか？ （これはもちろん珍しいはずです）
- 何かに「コードのにおい」があり、何らかの方法でリファクタリングを検討する価値があることをコードにメモします。
- コードにメモを入れて、その場所にクラッジが押し込まれた理由を説明します。これは、前のポイントとかなり似ています。
私が言及していないことの1つは、あなたが何かをした理由だけでなく、変更を加えたバグ追跡またはプロジェクト管理システムのタスク番号への参照です。すべてのためではありませんが、コードに奇妙な選択であるように見えるが、開発者がそうすることにつながる、長期にわたる意思決定プロセス（プロジェクト管理システムに文書化されている）があったという変更を加えるように求められましたそうするために複雑な理由があったか、後で私たちに噛まれるように戻ってくると感じた変更要求。 PMまたはバグ追跡システムで調べるタスク番号を前もって知ることは、後で要件が実際に変更されたかどうか、または新しい要件が古い要件を採用していないかどうかを確認するときに非常に役立ちますアプリケーションがそのように動作する理由の背後にある理由をすばやく見つけることができたため、いくつかの悪い将来の変更が無効になっています。
このサイトを検索すると、すでにいくつかの回答が提供されており、さらに多くの回答が存在します。私があなたに注目させたいのは次のとおりです。
コメントをお願いする前に、一連のルールと、コメントの形式（長さ）、内容、スコープ、およびコメントを使用するタイミングの例を考えてください。
アプリケーション内のビジネスルールはできるだけ記述しないでください。コードは、外部のドキュメントでビジネスルールを参照する場合がありますが、コード内で口頭で述べるべきではありません。