typescript-clean-code

クリーンコード

変更の形に関する12のコードスメル

Shotgun Surgery · Feature Envy · Data Clumps · Long Method · Divergent Change · Duplicated Code · Large Class · Long Parameter List · Primitive Obsession · Message Chains · Dead Code · Speculative Generality

それぞれのコードスメルと、そのリファクタリング方法はご存じでしょう。価値があるのは定義ではなくチェックリストです。名前がなければ差分は「問題なさそう」に見えますが、名前があればその形に気づけます。レビューする変更でも、自分で書く変更でも、12項目すべてを確認してください。

コードスメルのカタログは4つのレイヤーで構成されています

それぞれ異なる単位を調べるため、ほかのレイヤーが見落とすものを見つけられます。

読み込むもの	単位	用途
references/smells/tooling.md	リポジトリ	すべてのレビューで最初に確認します。 リンターで判定できるコードスメルを調べます。そうすれば、手書きの指摘を20件挙げる代わりに、「これを CI に組み込む」という指摘を1件にまとめられます
references/smells/rules.md	行、関数	行ごとのヒューリスティクス（C/E/F/G/N/T）に加え、4つすべてのレイヤーを統制するレビューの姿勢と重要度の語彙
references/smells/fowler.md	変更	前述の12項目それぞれについて、検出時の問い、TypeScript での対処法、そして修正しない場合を説明します
references/smells/typescript.md	型	TS1-TS10：any の漏出、アサーションと検証の違い、網羅性、strictness フラグ、ブランド型

差分が rules.md のルールをすべて満たしていても、構造に問題がある場合があります。それを見つけるのが fowler.md です。変更のレビューでは、4つすべてのレイヤーを確認します。

レビューの姿勢

カタログのどの項目よりもレビュー結果に大きく影響する3つのルールです。全文は references/smells/rules.md →「レビューの姿勢」を参照してください。

1. 完璧な変更ではなく、コードの健全性を向上させる変更を承認します。 完璧なコードはなく、あるのはより良いコードだけです。
2. 誰も対処しない正しい指摘は、偽陽性です。 幅広く確認し、選んで報告してください。対応可能な指摘3件のほうが、正しい指摘20件より有益です。
3. 細かな仕上げは無視できるものとして示します。 Conventional Comments のラベルである issue、 suggestion、nitpick、question、praise に (blocking) / (non-blocking) を付けます。どのコメントが任意なのか作者が判断できないと、すべて必須だと思うか、どれも必須ではないと思ってしまいます。

レビューが完了するのは、 4つすべてのレイヤーを確認し、残ったすべての指摘にラベルが付いており（issue には）修正方法が示され、対処される可能性が低いために除外した指摘の数をレポートに記載したときです。

異論のあるルール

これらのリファレンスには、現在も異論がある立場を示すルールが3つあります。該当箇所には 異論ありと記されています。両方の見解を示し、数よりも作者が実際に示した根拠を重視してください。

• 関数の長さ — references/functions/rules.md Rule 1。*「各セクションに名前を付けられるか？」*で検出します。「2-5 lines」という数字を文字どおりに適用すると、抽出しすぎになります。
• コメント — references/comments/rules.md。根拠、不変条件、すぐには明らかでない理由は残し、言い換えや古くなったコメントは削除します。
• G23 のポリモーフィズム — references/smells/rules.md。判別可能なユニオン型を網羅する switch は、慣用的な TypeScript であり、コードスメルではありません。

ワークフロー

workflow.md を読み込んでから、各ステップのファイルを順番に読み込みます。各ステップには必要なリファレンスが記載されており、出力ドキュメントのフロントマターにある stepsCompleted が更新されます。そのため、コンテキストが圧縮された場合も、最後に完了したステップから step-01b-continue.md を使って再開できます。

ワークフロー	用途
workflows/code-review/workflow.md	コードの品質をレビューする
workflows/pr-review/workflow.md	プルリクエストをレビューする
workflows/refactoring/workflow.md	テストを使って安全にリファクタリングする（ステップ3ですべての12項目を確認し、ステップ5～8を繰り返します）
workflows/tdd.md	テスト駆動開発のサイクル
workflows/new-feature.md	新機能を構築する
workflows/bug-fix.md	バグを適切に修正する
workflows/test-strategy.md	テストカバレッジを計画する
workflows/estimation.md	タスクを見積もる（PERT）
workflows/deadline-negotiation.md	非現実的な期限に対処する

参考資料

references/<topic>/ には、rules.md（ルール）、examples.md（厳選された TypeScript の悪い例／良い例のペア。独自に作成するより、こちらを優先してください）、knowledge.md（概念）が含まれています。

コード品質：命名 · 関数 · クラス · コメント · エラー処理 · 単体テスト · フォーマット · コードの臭い

プロフェッショナルな実践：プロ意識 · 断ること · コミットメント · コーディングの実践 · TDD · 練習 · 受け入れテスト · テスト戦略 · 時間管理 · 見積もり · プレッシャー · コラボレーション

トピックについて助言する前に、そのトピックの rules.md を読み込み、適用したルールを引用してください。引用するのは、そのルールが指摘する設計上の問題であり、それを示した指標ではありません。参考資料が一般知識と矛盾する場合は、参考資料を優先してください。このスキル向けの TypeScript の調整内容としきい値が記載されています。

guidelines.md には、症状 → 参考ファイル、タスク → ワークフローの対応が記載されています。