コードにコメントする必要がある[しない]理由

最近、コード内のコメントは必須ではなく、有害でさえあるという考えが人気を集めています。 昨夜、若いプログラマーの友達にコードを見せてほしいと言ったところ、私は、メソッドの通常の説明でさえ、まったくコメントがないことがわかりました。 驚いた絵文字には、「 コメントは悪いコードの最初の兆候です 」という答えがありました。 そして、彼と地獄に、初心者プログラマーで、しかし私は定期的にブログで似たようなものを読んで、同僚から話を聞いた。 プログラミングが再び一歩前進したのかもしれませんが、私は遅れを取っているのでしょうか？ カットの下で、コードにコメントする価値があるかどうか、コメントする価値があるかどうかについて少し考えました。



したがって、コード内のコメントに対する2つの主要なステートメントがあります。

ステートメント1：「コードはそれ自体が最高のドキュメントです。」

または、より過激な「 コメントは悪いコードの最初の兆候です 。」

原則として、アイデアは真実であり、コードはクリーンでなければなりません。 きれいなコードはコメントを必要としません;とにかく理解できます。 この変数の意味をコメントで説明したい場合は、名前から明らかになるように名前を変更する方が良いでしょうか？ メソッドのアルゴリズムが少し混乱しているように思われる場合、おそらくコメントを書く代わりに、アルゴリズムを書き直して、より理解しやすく論理的にする価値がありますか？



残念ながら、実生活では、美しく論理的なコードを作成できるとは限りません。 場合によっては、品質のリファクタリングに十分な時間がなく、できる限り書くだけです。 ビジネスロジック自体が非常に混乱しているため、100グラムがなければ実現できないこともあります。 そして、気づいたら、このタスクを忘れて、念のため、シャワーを5回ほど行います。 そして時々、あなたにとって美しく論理的なものが同僚に困難をもたらす可能性があります。



それでは、コード自体が最高のドキュメントになるのでしょうか？ もちろん、それはできますが、確かに、余分なコメント行を挿入することを恐れないでください、または少なくとも使用されたパターンへの参照をしてください。 おそらく将来、これにより誰かが少し時間を節約できるでしょう。

ステートメント2：「コメントは古い可能性があります。」

コメントはある時点でコードに対応しなくなる可能性があることが理解されます。 たとえば、前の段落によると、同僚の時間を節約したいので、本文に多くのコメントを残した特定のメソッドを作成しました。 半年後、同僚は方法を変更しましたが、急いで、または無分別で、コメントを修正するのを忘れました。 そして半年後、あなたの同僚は無関係なコメントに惑わされたため、多くの時間を失いました。

問題は大げさなものではありません。たとえば、コードに対応していないコメントに何度も出会ったことがありますが、そこに何があるのでしょうか。 問題はありますが、コメントをまったく除外することが最善の解決策だとは思いません。 あなたはただ注意する必要があり、コードを修正するときにコメントを修正することを忘れないでください。

なんで？

誤解しないでください、私はすべての行にコメントを求めるキャンペーンをしていません。 さらに、私自身は次のスタイルのコメントを検討します。

$i++; //  

      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

. ! !



“?”, “?”. , . , , “ ? !”, , , . . , , . — .

.

, . : “, , ”. - , — , , . , , , , .