Comments

Comments（コメント）

兆候と症状
メソッドが説明コメントで埋め尽くされている状態。

問題の理由
コメントは通常、プログラム作成者が自分のコードが直感的でも明快でもないことに気付いたときに、それを改善する目的で記載されます。そのような場合、コメントは、改善されるべき臭いのするコードに消臭剤を撒いて臭いを隠すようなものです。

もっとよいコメントはメソッドやクラスに良い名前を付けることです。

コメントがないと理解できないようなソースコードは、コメントが不要になるようにコード構造を変更してみてください。

対処

• コメントが複雑な式を説明することを目的としている場合、式は「Extract Variable」を使用して理解可能な部分式に分割する必要があります。
• コメントがコードのセクションを説明している場合、このセクションは「Extract Method」を介して別メソッドとして抽出できます。新しいメソッドの名前はコメントを参考にしましょう。
• メソッドがすでに抽出されているが、メソッドが何をするのかを説明するためにコメントが必要な場合は、メソッド名をわかりやすいものにします。これには「Rename Method」を使用します。
• システムが機能するために必要な状態に関するルールをアサートする必要がある場合は、「Introduce Assertion」を使用します。

効果

• コードがより直感的で明確になります。

When to Ignore
時としてコメントは有用なものです。

• 特定の方法で実装されている理由を説明するとき。
• 複雑なアルゴリズムを説明するとき（アルゴリズムを簡素化する他のすべての方法が試され、不足しているとき）。

書籍としてはこの辺りが参考になると思います。

リファクタリング第2版


レガシーコード改善ガイド