clean-comments

コメントをクリーンに保つ

C1：不適切な情報を書かない

コメントにメタデータを含めてはいけません。作成者名、変更履歴、チケット番号、日付は Git で管理します。コメントにはコードに関する技術的なメモだけを書きます。

C2：古くなったコメントを削除する

コメントが、もう存在しないコードや以前とは異なる動作を説明している場合は、すぐに削除します。古くなったコメントは「無関係で誤解を招く孤島」になります。

C3：冗長なコメントを書かない

// Bad - the code already says this
i += 1; // increment i
user.save(); // save the user

// Good - explains WHY, not WHAT
i += 1; // compensate for zero-indexing in display

C4：質の高いコメントを書く

コメントを書く価値があるなら、質の高いものを書きます。

• 言葉を慎重に選びます
• 文法を正しく使います
• 冗長にならず、自明なことを書きません
• 簡潔にします

C5：コメントアウトしたコードを絶対にコミットしない

// DELETE THIS - it's an abomination
// function oldCalculateTax(income: number): number {
//   return income * 0.15;
// }

どれだけ古いのか、意味があるのか、誰にもわかりません。削除しましょう。 Git がすべてを記憶しています。

目標

最良のコメントはコードそのものです。コードの動作を説明するコメントが必要なら、まずリファクタリングし、コメントは最後に書きます。