code-quality

Python コード品質

レビューまたはセルフレビューで確認すべき、価値の高い Python のコード品質アンチパターンです。 このスキルはレビューに重点を置いており、テストの仕組み（pytest）やコードベース全体の健全性評価（code-quality-scoring）とは別に、レビュー担当者（またはリンター）が指摘すべき正確性と可読性の欠陥を扱います。

出典に関する注記： これらのアンチパターンは、CAST Highlight の Python コード品質指標（https://doc.casthighlight.com/）をもとにしており、主な情報源として PEP 8 と Python のデータモデルを参照しています。ルールが PEP 8 を反映している場合は、PEP が正式な情報源です。例はすべて独自に作成したものです。

このスキルを使う場面

タスクが 「この Python コードはきれいで正確か？」 という内容の場合に使用します。たとえば、次のような場面です。

• プルリクエストをレビューし、以下の欠陥がないか確認する。
• PR を作成する前にセルフレビューする。
• ruff／pylint／mypy のルールを設定し、CI でこれらを自動検出する。
• チームの Python コード品質ガイドラインを作成または更新する。

テストの仕組みには使用しないでください（pytest スキルを使用してください）。また、コードベース全体の健全性や技術的負債の評価にも使用しないでください（code-quality-scoring スキルを使用してください）。

中核となるアンチパターン（概要）

価値の高い Python のアンチパターンを6つ紹介します。それぞれに、準拠していない例と準拠している例、およびリファレンスドキュメント内の「テスト方法」に関する注記があります。

• カスタム例外は Exception を継承する必要があります — object を継承した、送出することを意図したクラスは実行時に失敗し、すべての except 節を壊します。
• シングルトンの比較には == ではなく is を使います — None／True／False には is／is not を使います（PEP 8）。is はシングルトンにのみ使用し、値の比較には決して使わないでください。
• 裸の／過度に広範な except を避けます — 処理できる最も限定的な型を捕捉します。汎用的な except Exception は、最後の手段としてログを記録するか再送出する場合に限って使用します。
• ワイルドカードインポートを避けます（from x import *）— 依存関係が見えにくくなり、意図しない名前の衝突が発生するおそれがあり、静的解析も妨げます。
• マジックナンバーを名前付き定数に置き換えます — 自明でないリテラルは、説明付きの名前付き定数にします。
• 未使用のローカル変数を削除します — 使われない代入は読み手を誤解させ、値を使うべきだった箇所にあるバグを隠すおそれがあります。

ベストプラクティス

• CI でこれらをチェックします。 多くは ruff（ワイルドカードの F403／F405、未使用のローカル変数の F841、シングルトン比較の E711／E712）、pylint、mypy で低コストにチェックできます。レビューの労力を仕組みではなく判断に集中できるよう、CI に lint ステップを追加してください。
• 具体的な例外ハンドラーを優先します。 ハンドラーは限定的な型から順に並べ、汎用的な except Exception は、ログ記録または再送出を行う最後の手段としてのみ使用します。
• 値ではなく意図に名前を付けます。 定数の名前によって、しきい値を設けた理由が伝わります。単なるリテラルからは何も伝わりません。

アンチパターン（避けるべきもの）

• カスタム例外が object または BaseException を直接継承している。
• == None、== True、または is "some literal"。
• 制御フローのシグナルを握りつぶす裸の except: または except BaseException:。
• 明示的な __all__ を持つ、内容を精選した __init__.py 以外での from module import *。
• ビジネスロジック内の、説明のない数値リテラル。
• 古いリファクタリングの名残として残された、代入されているが一度も読み取られないローカル変数。

ナビゲーション

• quality-antipatterns.md：6つのアンチパターンそれぞれについて、準拠していない例と準拠している例、および「テスト方法」に関する注記を掲載しています。

関連スキル

• pytest（toolchains/python/testing/pytest）：テストの仕組み — フィクスチャ、パラメーター化、モック。ここに挙げたアンチパターンのうち、いくつか（広範な except、不正な例外クラス）は、テストを不安定にする直接の原因になります。
• code-review-standards（universal/process/code-review-standards）：これらに相当する項目を取り入れた、プロジェクト全体で使用する重大度タグ付きレビュー用チェックリストです。
• code-quality-scoring（universal/quality/code-quality-scoring）：個々の指摘事項ではなく、コードベース全体の健全性と技術的負債を評価します。