開発のどの段階でコメントを書くべきですか？
私は大企業でインターンシップに従事し、C＃で中小企業向けアプリを作成している学生です。私はコードを書いているときにコメントしないことに気づきました。むしろ、開発のデバッグ段階にあるときにコードにコメントします。バグを追跡しているときに、「うーん...将来誰かを混乱させるかもしれない。コメントしたほうがいい」と思わせるブロックに出くわし、適切なコメントを追加します。私のコメントはすべてこの方法で行われます。
これはコメントの適切な方法ですか？コードを書くときにコメントを書くべきですか？または、このブロックが使用される理由を適切に説明している限り、コメントがいつ書き込まれるかは本当に重要ですか？
コードは可能な限り自己記述的である必要があります。つまり、明確なコードを記述すれば、必要なコメントは少なくなります。
コメントを含める必要があります：
- クラス/メソッドの概要とその機能
- 全体的なアーキテクチャとしてのオブジェクトとメソッドの相互関係。
- あいまいなパフォーマンス最適化など、コードを読んでもすぐに分からないもの。
一般に、コメントは必要なときに書き込む必要があります理想的には、コメントを必要とするコードを記述するときに使用します。
明白であることを示すコメントを避けたり、コードですでに明確になっていることを再度述べたりしないでください。コメントが多いほど、コードを変更したときに維持しなければならないコメントも多くなります。
理論的根拠とコンテキストが心の中でより新鮮であるため、開発の最初からコメントを書く人をむしろ勧めたいと思います。このような意図を思い出すのは時間が経つにつれて指数関数的に困難になる可能性があるため、これによりかなりのメンテナンス作業を節約できます。
コードのコメントにはいくつかの経験則がありますが、私は実用的な使用のために簡略化したリストを用意しています。
- whatが完了したことを簡潔に伝える
- howはコードに任せてください。明らかでないものまたは一般的な方法論（よく知られているソリューション、アルゴリズム、または関係の参照など）にのみコメントします。
- 非慣用的言語の使用を正当化する必要があるときはいつでも（通常、パフォーマンスのトリックにはそれが必要です）
これらすべての項目は、適切なピアレビュープロセスによってより適切に認識されます。
コードを書くときにコメントを書いてください。それらはあなたの利益のためだけでなく、後でコードを読んでいる可能性のある人の利益のためにあります。
「このブロックが使用される理由を説明する」と話すと、物事は半分正しいと思いますが、デバッグ段階では遅すぎます。この後の段階でなぜ特定の方法で物事を書いたのかを考える必要がある場合は、すでにコードの作成中にコメントを書き込んだ方が時間と手間を省けるはずです。
また、コーディング中に心を集中させるのにも役立ちます。急いで何かを急がせるのではなく、あなたがやっていることをもう少し考えてください今、そしてあなたが間違ったトラックに行くのを防ぐことができます。
これは、あなたがコードを書いている間にonlyがコメントを書くべきであると言っているわけではありません。後の段階（デバッグだけでなく）でさらにコメントを追加するのが適切と思われる場合は、既存のコメントを変更するか、以前になかった場所に新しいコメントを追加（または、不要になったものを削除）してから、追加します。あまりにも。
理想的には、コメントはコードと同時に書き込む必要があります。
現実の世界では、これらのコメントは実際に書かれる必要があるほど頻繁ではないので、あなたの意見では、追加のコメントに値するコードに出くわした場合、後で追加すること（またはコメントすること）には何もないはずです。レビュー中に見つけた場合）。
ほとんどの場合、コードの前と代わりにコメントを書きます。このようにして、将来のコードの計画を大まかに説明します。
次に、コメントが示唆するコードを追加します。コメントにはwhatとwhyが記述され、コードにhowが追加されます。
その後、コードが十分に透過的である場合、一部のコメントが編集される可能性があります。一部の（はるかに少ない）コメントを展開する必要があります。
この方法では、既存のコードにコメントを追加する必要はほとんどありません。
あなたのメソッドはうまく機能します[〜＃〜] iff [〜＃〜]あなたが書いたすべてのコードは完全にデバッグされますあなたはそれをコメントするために多くのパスを持っています。うまくいけば、あなたはいつか最初の試行でうまくいく（多かれ少なかれ）もっと多くのコードを書くでしょう。これは、「ルールのデバッグ時にのみコメント」に厳密に従う場合、デバッグセッションが少なくなるか、長くならないことを意味します。つまり、コメントが少なくなるか、まったくないことを意味します。
コードを書くときにコメントを書いてください。追加の説明が必要と思われるコードを書く場合は、コメントが必要になるとわかったらすぐにコメントを書き込んでください!!
（はい、コメントが無効になるようにコードが変更された場合、willはコメントを更新する必要があります）
コメントはどの段階でも書くことができます。コードに説明が必要であると信じ、それを理解していることがわかっている場合は、コメントを書く必要があります。
コードに説明が必要であると信じることは、ほとんど常にコードの目的を理解するのがいかに簡単であるかについてのあなたの考えに基づいているべきです-目的が明確であれば、おそらくそれが何をしているかについての説明は必要ないでしょう。これは部分的に適切な命名の目的です。関数の名前とその入力/出力が与えられると、コードが必要な理由と、コードが実行していることを実行している理由を理解できます。
構文に関するコメントは非常にまれであり、あいまいであり、他のものと誤解される可能性がある場合に限定されます。単にあいまいな場合は、必要に応じて調べてもらい、_a + b * c_を単に誤解している可能性がある場合は、a + (b*c)を誤解しないように記述します。一方、目的が不明確な場合（極端な例ではフレームワーク/コンパイラのバグを回避する）、次の人があなたがしていることをしている理由を理解できるようにコメントが必要です。
デバッグ時にコメントを追加しても問題ありません。デバッグを行うと、当然、理解するのに苦労する可能性のある古いコードに戻ります-理解するのに苦労して、コメントが必要であることがわかります。
これが、多くの人々が構文についてのコメントを書き始める理由かもしれません-彼らはまだそれを習得しておらず、まだ少し苦労していて、構文が彼らが学ぶものであることを理解するのに十分な経験がありません後で理解する。彼らは構文の理解に問題があると予想しているため、コメントを提供します。
ただし、これを通常の操作モードとして使用することは理想的ではありません。せいぜい、2回目にそのコードをデバッグする必要がある場合に役立ちます。コードの理解に問題が発生する場所を予測し、それが記述されているとおりにそれを説明するコメントを書き込むように努める必要があります。常に、最初はほとんどの場合、正しく機能するとは思わないでください。より良いことをしてみてください。