1. 命名規則

PEP-8 に準拠した命名はスネークケースを推奨します。関数名は動詞＋名詞の組み合わせで意図を明確に表現します。

def update_customer_name(name: str) -> None:
    pass

型ヒントを活用することで、IDE や静的解析ツールでの補完が効率化されます。ただし、実行時の型強制ではない点に注意が必要です。

def register_member(handle: str, birth_year: int) -> dict:
    """
    Parameters:
        handle: ユーザー識別子（英数字3-20文字）
        birth_year: 西暦年（1900-現在年）
    Returns:
        生成された会員情報辞書
    """
    return {"id": handle.lower(), "generation": birth_year}

2. 単一責任の原則

1つの関数は1つの責務のみを持つべきです。以下の例では、データ取得・フィルタリング・分類の3つの処理が混在しています。

def fetch_raw_members():
    # データソースから生データを取得
    pass

def filter_by_age_range(records, min_age, max_age):
    # 年齢区間で絞り込み
    pass

def group_by_membership_type(filtered):
    # 会員種別で分類
    pass

適度な粒度が重要です。過度な細分化も可読性を損ないます。

3. Docstring の整備

Google スタイルや NumPy スタイルなど、プロジェクト内で統一した形式を採用します。

def verify_account_exists(role: str, account_id: str) -> bool:
    """アカウントの重複有無を確認する。

    Args:
        role: "instructor" または "learner"
        account_id: システム内で一意の識別子

    Returns:
        True: 既に存在する / False: 未登録で利用可能
    """
    pass

help() または __doc__ 属性で確認できます。

4. 返り値の設計

複数値の返却は暗黙的にタプル化されます。意図を明確にするため、明示的な構造を推奨します。

def calculate_metrics():
    # 非推奨: 暗黙のタプル
    # return 10, 20, 30
    
    # 推奨: 名前付きタプルやデータクラス
    from collections import namedtuple
    Metrics = namedtuple("Metrics", ["precision", "recall", "f1_score"])
    return Metrics(precision=0.92, recall=0.88, f1_score=0.90)

何も返さない関数は暗黙的に None を返します。処理結果の成否を bool で返すなど、意味のある返り値を設計しましょう。

5. 適切な関数規模

視覚的な認知負荷を考慮し、50行程度を目安に分割を検討してください。同一入力に対して決定論的な出力を返す「純粋関数」を意識すると、テスト容易性が向上します。

def apply_discount(base_price: int, coupon_code: str | None) -> int:
    """副作用のない計算処理の例"""
    if not coupon_code:
        return base_price
    rate = COUPON_MAP.get(coupon_code, 0)
    return int(base_price * (1 - rate))