python-guidelines

Python ガイドライン

既存のコードに統合してください。後付けしないでください。

シンプルであることは、複雑であることに勝ります。フラットであることは、ネストされていることに勝ります。 エラーを黙って無視してはいけません。明示的に抑制する場合を除きます。 実装を説明するのが難しいなら、それは悪いアイデアです。

-- Python の禅（PEP 20）

コードの方針

• 既存の命名、インポート、シグネチャのパターンに合わせてください。既存のユーティリティとデータ構造を使用してください。
• 関数の目的は1つにしてください。汎用性を損なうような動作をハードコードしないでください。
• 2行以下の単純なラッパーは作成しないでください。インライン化してください。
• 1回しか使わない変数は、使用箇所にインライン化してください。
• 重大な理由がない限り、try/exceptを使わないでください。エラーは表面化させてください。
• コードを重複させないでください。
• 関数は独自に入力を検証してください。メイン処理にif-elseチェックを置かないでください。
• os.pathではなくpathlibを使用してください。
• MongoDB/Gemini/OpenAI/Claude/VoyageのAPIと時間のコストを考慮してください。

次のようにしないでください。

# Generate comment report only if requested
if include_comments:
    comment_report = generate_comments_report(start_date, end_date, team, verbose)
else:
    comment_report = ""
    print("   Skipping comment analysis (disabled)")

次のようにしてください。

comment_report = generate_comments_report(start_date, end_date, team, verbose) if include_comments else ""

自問してください。「コードを追加しているのか、それとも既存のものに統合しているのか？」

抽象化よりシンプルさを優先

YAGNI：今は必要ないものは作らない。

仮定上の将来の要件に備えて作らないでください。現在のタスクで必要な場合にのみ、複雑さを加えてください。

次のことは避けてください。

• 実装が1つしかないのに抽象基底クラスを作成する
• 誰にも求められていない設定オプション
• 起こり得ない状況へのエラー処理
• 1つの関数を囲むラッパークラス
• 直接呼び出しで十分なのに依存性注入を使う
• 具体的な型が1つしかないのにジェネリック型パラメーターを使う

似たコードが3行あるほうが、時期尚早な抽象化より優れています。実際に3つ目のユースケースが現れてからリファクタリングしてください。それまでは行わないでください。

ただし、シンプルさは無秩序を意味しません。常に次の点を維持してください。

• 関数の内容を明確に示す名前
• 関連するコードをモジュール内で論理的にまとめる
• プロジェクト全体で一貫した命名規則
• I/Oとロジックを明確に分離する
• グローバル状態や副作用よりも明示的なパラメーターを使う

自問してください。「この抽象化は、今まさに抱えている問題を解決しているのか、それとも想像上の問題を解決しているのか？」

環境

• パッケージマネージャー：uv（pipではありません）
• 仮想環境：source .venv/bin/activate または uv run python -c "..."
• サードパーティ製パッケージ：python -c "import pkg; print(pkg.__file__)" でソースを探し、Readしてください。

テストの規律

何事も決めつけないでください。コードの動作、パッケージ関数、データ構造に関する仮説を検証してから、計画を提案したりプランモードを終了したりするために、python -c "..." を実行してください。

自問してください。「これを前提に進める前に、python -c で検証したか？」

Googleスタイルのdocstring

• 要約：命令形（「Calculate」。 「Calculates」ではありません）
• Args：すべてのパラメーターについて、型と説明を記載します。デフォルト値は記載しません。インデントは4スペースです。
• 型：int | str のようなユニオン、(N, M) のような大文字の形状、list/dict/tuple のような小文字の組み込み型、Any/Path は大文字で始めます
• Optional：name (type, optional): 説明
• Returns：必ず (type) の形式で括弧内に記載します。タプル型は使いません。複数の戻り値には名前を付けて個別に記載します。
• セクション：Examples（>>>）、Notes、References（プレーンテキストのみ）。セクションタイトルのインデントは0です。
• 省略するもの：何も返さない場合は「Returns:」、引数がない場合は「Args:」、重大な理由がない限り「Raises:」を省略します
• クラス：Attributesセクションのみを記載し、Methods/Argsは省略します。1行の記述を複数行に変更しないでください。
• __init__：Argsのみを記載します。Examples/Notes/Methods/Referencesは記載しません。
• テスト：docstringは1行のみとします。
• 既存の引数説明からデフォルト値を削除してください。最小限のExamplesは任意で追加できます。

自問してください。「新しい開発者は、このdocstringだけで関数を理解できるか？」

参照ファイル

コードを書く前に、該当するファイルを読んでください。書いた後ではありません。

• references/idiomatic-patterns.md -- ループ、内包表記、アンパッキング、コンテキストマネージャー、データクラスを書くときに読みます。前後のコード例を含む 18 のイディオム
• references/zen-of-python.md -- 2 つの設計から選ぶときや、抽象化に存在意義があるか判断するときに読みます。注釈付きの PEP 20
• references/google-style-guide.md -- 例外、ミュータブルなデフォルト値、インポートのスタイル、命名、コメントについて判断するときに読みます
• references/effective-python-tips.md -- 既存のコードをレビューまたはリファクタリングするときに読みます。「Effective Python」（Brett Slatkin）からの重要なヒント