class RateLimiter:
    def should_allow(self, client_id: str) -> bool:
        # Sliding Window アルゴリズムを使用。
        # Fixed Window だとウィンドウ境界でバーストが発生するため。
        # 例: Fixed Window で100リクエスト/分の場合、
        # 59秒目に100リクエスト + 次の分の0秒目に100リクエスト
        # = 実質1秒間に200リクエスト通過してしまう。
        # 参考: https://blog.cloudflare.com/counting-things-a-lot-of-different-things/
        window_start = time.time() - self.window_size
        request_count = self.store.count_since(client_id, window_start)
        return request_count < self.max_requests
 
    def _cleanup_old_entries(self):
        # Redis のメモリ使用量を抑えるため、古いエントリを定期削除。
        # 本来TTLで自動削除されるが、大量のキーがある場合
        # Redis の lazy deletion が追いつかないことがある。
        # (Redis 6.0 以降は active-expire-effort で調整可能だが、
        #  パフォーマンスへの影響が読みにくいため明示的に削除する方針)
        cutoff = time.time() - (self.window_size * 2)
        self.store.delete_before(cutoff)

class PaymentProcessor:
    def process(self, payment: Payment) -> PaymentResult:
        # Stripe API はべき等キーによる重複防止をサポート。
        # ネットワーク障害時のリトライで二重課金を防止するため、
        # 注文IDをべき等キーとして使用する。
        # 参考: https://stripe.com/docs/api/idempotent_requests
        idempotency_key = f"payment-{payment.order_id}"
 
        try:
            charge = stripe.Charge.create(
                amount=payment.amount,
                currency="jpy",
                idempotency_key=idempotency_key,
            )
            return PaymentResult.success(charge.id)
        except stripe.error.CardError as e:
            return PaymentResult.failure(str(e))

public class UserSearchService {
    public List<User> searchByName(String query) {
        // 全文検索インデックスではなく LIKE 検索を使用。
        // 理由: ユーザー数が1万件未満のため、Elasticsearch の
        // 運用コスト (インフラ費用、運用工数) に見合わない。
        // ユーザー数が10万件を超えた場合は全文検索への移行を検討すること。
        // Issue: https://github.com/example/app/issues/567
        return userRepository.findByNameLike("%" + query + "%");
    }
 
    public List<User> findActive() {
        // ソート済みリストを返す。
        // UI側でページネーション + 無限スクロールを使用しており、
        // 一貫した順序が保証されないとスクロール時にアイテムが
        // 重複・欠落するため。
        return userRepository.findByStatus(Status.ACTIVE, Sort.by("id"));
    }
}

class SessionStore:
    def __init__(self):
        # Redis ではなくインメモリ辞書を使用。
        # トレードオフ:
        #   利点: 外部依存なし、レイテンシ最小、開発環境構築が容易
        #   欠点: プロセス再起動でセッション消失、水平スケール不可
        # 現状はシングルインスタンスでの運用のため許容。
        # マルチインスタンス構成への移行時に Redis に切り替える。
        # 判断日: 2024-01-15, 判断者: アーキテクチャレビュー会議
        self._sessions: dict[str, Session] = {}

/*
 * Copyright (c) 2024 Example Corp.
 * Licensed under the MIT License.
 * See LICENSE file in the project root for full license information.
 */

# SPDX-License-Identifier: Apache-2.0
# Copyright 2024 Example Corp.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.

# WARNING: この関数はスレッドセーフではない。
# マルチスレッド環境で使用する場合は外部で排他制御が必要。
# threading.Lock() または concurrent.futures の使用を推奨。
def update_global_cache(key: str, value: any) -> None:
    global_cache[key] = value
 
# CAUTION: この処理は平均2秒かかる（最大10秒）。
# ユーザー向けのリクエストパスでは使用せず、
# バックグラウンドジョブ (Celery等) 経由で呼び出すこと。
# 直接呼び出すとリクエストタイムアウトが発生する。
def rebuild_search_index() -> None:
    pass
 
# NOTE: この定数は外部 API の仕様に基づく。
# 変更する場合は API ドキュメントを確認すること。
# https://api.example.com/docs#rate-limits
MAX_REQUESTS_PER_MINUTE = 60
 
# IMPORTANT: 以下の処理順序を変更しないこと。
# 在庫確認 → 決済 → 在庫引き当ての順序でないと
# 在庫の二重引き当てが発生する。
# 過去にこの順序を変えて本番障害が発生（2023-06 P1 インシデント）。
def process_order(order: Order) -> None:
    check_inventory(order)      # 1. 在庫確認
    process_payment(order)      # 2. 決済
    reserve_inventory(order)    # 3. 在庫引き当て

# TODO(#1234): v2.0でOAuth2に移行予定。Basic認証は非推奨。
# 期限: 2025-Q2
# 担当: auth-team
def authenticate_basic(username: str, password: str) -> bool:
    pass
 
# FIXME(#2345): 大量データ（100万件以上）で OOM が発生する。
# 原因: 全件メモリ展開しているため。
# 対策: ストリーミング処理に変更する。
def export_all_users() -> list:
    return db.query("SELECT * FROM users")
 
# HACK(#3456): MySQL 5.7のバグ(#12345)を回避するためのワークアラウンド。
# MySQL 8.0にアップグレード後に除去すること。
# 参考: https://bugs.mysql.com/bug.php?id=12345
def query_with_workaround(sql: str) -> list:
    sql = sql.replace("GROUP BY", "GROUP BY 1, ")
    return db.execute(sql)
 
# OPTIMIZE(#4567): N+1 クエリが発生している。
# 現状はデータ量が少ないため許容しているが、
# テナント数が100を超えたら JOIN クエリに変更すること。
def get_tenant_users(tenant_ids: list[str]) -> list[User]:
    result = []
    for tid in tenant_ids:
        result.extend(db.query("SELECT * FROM users WHERE tenant_id = %s", tid))
    return result

# RFC 5322準拠のメールアドレスバリデーション
# ローカル部: 英数字、ドット、ハイフン、アンダースコア、プラス
# ドメイン部: ラベル（英数字+ハイフン）をドットで接続
# 参考: https://datatracker.ietf.org/doc/html/rfc5322#section-3.4.1
EMAIL_PATTERN = re.compile(
    r'^[a-zA-Z0-9._%+-]+'    # ローカル部
    r'@'                       # @ 記号
    r'[a-zA-Z0-9.-]+'         # ドメイン名
    r'\.[a-zA-Z]{2,}$'        # トップレベルドメイン
)
 
# 日本の電話番号バリデーション（固定電話 + 携帯電話）
# 形式1: 03-1234-5678（市外局番-市内局番-加入者番号）
# 形式2: 090-1234-5678（携帯電話）
# 形式3: 0120-123-456（フリーダイヤル）
# ハイフンあり/なし両方に対応
PHONE_PATTERN = re.compile(
    r'^0'                      # 先頭は 0
    r'[0-9]{1,4}'             # 市外局番（1-4桁）
    r'-?'                      # ハイフン（任意）
    r'[0-9]{1,4}'             # 市内局番（1-4桁）
    r'-?'                      # ハイフン（任意）
    r'[0-9]{3,4}$'            # 加入者番号（3-4桁）
)
 
# クレジットカード番号のマスキング
# 先頭6桁（BIN）と末尾4桁を残し、中間をマスク
# 例: 4111-1111-1111-1111 → 411111******1111
# PCI DSS 準拠: 表示時は先頭6桁+末尾4桁まで
MASK_PATTERN = re.compile(r'^(\d{6})\d+(\d{4})$')

# ダイクストラ法: 始点から全頂点への最短距離を計算
# 計算量: O((V + E) log V) where V=頂点数, E=辺数
# 負の重みがある場合はベルマンフォード法を使用すること
#
# アルゴリズムの概要:
# 1. 始点の距離を0、他の全頂点の距離を inf に初期化
# 2. 未確定頂点のうち距離最小のものを選択（優先度キュー使用）
# 3. 選択した頂点の隣接頂点の距離を更新（緩和操作）
# 4. 全頂点が確定するまで 2-3 を繰り返す
def dijkstra(graph: Graph, source: int) -> dict[int, float]:
    distances = {v: float('inf') for v in graph.vertices}
    distances[source] = 0
    priority_queue = [(0, source)]
    visited = set()
 
    while priority_queue:
        current_dist, u = heapq.heappop(priority_queue)
 
        if u in visited:
            continue
        visited.add(u)
 
        for v, weight in graph.neighbors(u):
            # 緩和操作: 既知の距離より短いパスが見つかったら更新
            new_dist = current_dist + weight
            if new_dist < distances[v]:
                distances[v] = new_dist
                heapq.heappush(priority_queue, (new_dist, v))
 
    return distances

class EventBus:
    def subscribe(self, event_type: str, handler: Callable) -> None:
        """イベントハンドラを登録する。
 
        同一イベントに複数のハンドラを登録可能。
        ハンドラは登録順に呼び出される（FIFO）。
 
        # なぜ順序保証するのか:
        # 監査ログハンドラがビジネスロジックハンドラより先に
        # 呼ばれる必要があるユースケースがあるため。
        # 順序に依存しない設計が望ましいが、現状の要件では必要。
 
        Args:
            event_type: イベントの種類を示す文字列。
            handler: イベント発生時に呼び出されるコールバック関数。
 
        Raises:
            ValueError: event_type が空文字の場合。
            TypeError: handler が callable でない場合。
        """
        self._handlers.setdefault(event_type, []).append(handler)

# -----  NG: コードをそのまま繰り返す -----
 
# ユーザー名を取得する
username = user.get_name()  # コードを見れば分かる
 
# カウンタをインクリメントする
counter += 1  # これは不要
 
# リストに追加する
items.append(new_item)  # 自明すぎる
 
# null チェック
if user is not None:  # コードそのまま
    process(user)
 
 
# ----- OK: コメントが不要なコード -----
 
username = user.get_name()
counter += 1
items.append(new_item)
if user is not None:
    process(user)
 
# もし「なぜ」がある場合のみコメントする:
# ユーザーが削除済みの場合でもグレースピリオド中は
# プロフィール表示が必要なため、None チェックが必要。
if user is not None:
    process(user)

# NG: 嘘のコメント（条件の説明が逆）
# 偶数かどうかをチェック
if number % 2 != 0:  # 実際は奇数チェック！
    process_odd(number)
 
# NG: 古くなったコメント（値の変更がコメントに反映されていない）
# 最大リトライ回数は3回
MAX_RETRIES = 5  # いつの間にか5に変更されている
 
# NG: 引数の説明が実態と不一致
def send_email(
    to: str,       # 送信先メールアドレス
    subject: str,  # 件名
    body: str,     # 本文（プレーンテキスト） ← 実際は HTML も送れる
) -> bool:
    pass
 
# NG: 戻り値の説明が間違っている
def find_user(user_id: str):
    """ユーザーを取得する。見つからない場合は None を返す。"""
    # 実際は見つからない場合 UserNotFoundError を raise する
    user = db.query("SELECT * FROM users WHERE id = %s", user_id)
    if not user:
        raise UserNotFoundError(user_id)
    return user
 
 
# OK: コメントを修正するか、コードを改善する
def is_odd(number: int) -> bool:
    """数値が奇数かどうかを判定する。"""
    return number % 2 != 0
 
if is_odd(number):
    process_odd(number)

# NG: コメントアウトされたコードの放置
def calculate_total(items):
    total = sum(item.price for item in items)
    # tax = total * 0.08  # 旧税率
    # discount = total * 0.05 if is_member else 0
    # total = total + tax - discount
    # if apply_coupon:
    #     total = total * 0.9
    tax = total * 0.10
    return total + tax
 
# なぜダメか:
# 1. 「削除して大丈夫なのか？」と読み手が悩む
# 2. 何の目的で残されているのか不明
# 3. コードの流れが読みにくくなる
# 4. Git に履歴があるので復元可能 → 削除すべき

# NG: 属人的なコメント ── 個人に依存する情報
# 田中さんに確認済み (2023/01/15)
# TODO: 佐藤くんが後でリファクタリングする
# この部分は山田さんしか分からない
# 鈴木さんの要望で追加した機能
 
# OK: 客観的な情報として記載
# 2023-01-15 承認済み: 金融庁ガイドライン準拠の確認完了 (Issue #789)
# TODO(#1234): パフォーマンス改善のためクエリをリファクタリング
# NOTE: このロジックの仕様は docs/pricing-algorithm.md を参照
# 要件: チケット #567 で追加された割引機能

# NG: ファイル内の変更履歴（Git が担うべき役割）
# 変更履歴:
# 2024-01-01 田中: 初版作成
# 2024-02-15 佐藤: バリデーション追加
# 2024-03-20 鈴木: パフォーマンス改善
# 2024-04-10 田中: バグ修正 (#1234)
 
# 代替手段: Git コマンドで確認
# → git log --oneline -- path/to/file.py
# → git blame path/to/file.py
# → git log --author="田中" -- path/to/file.py

# NG: コメントで構造を区切る（God Class の兆候）
class UserService:
    ##################################
    # ユーザー関連の処理
    ##################################
    def create_user(self): ...
    def update_user(self): ...
    def delete_user(self): ...
 
    ##################################
    # 認証関連の処理
    ##################################
    def login(self): ...
    def logout(self): ...
 
    ##################################
    # 通知関連の処理
    ##################################
    def send_email(self): ...
    def send_sms(self): ...
 
# OK: クラスやモジュールで責務を分離する
class UserService:
    def create_user(self): ...
    def update_user(self): ...
 
class AuthService:
    def login(self): ...
    def logout(self): ...
 
class NotificationService:
    def send_email(self): ...
    def send_sms(self): ...

# NG: ノイズコメント
class User:
    def __init__(self):
        """デフォルトコンストラクタ"""  # 何も情報を追加していない
        pass
 
    def get_name(self) -> str:
        """名前を取得する"""  # メソッド名と同じ
        return self.name
 
    def set_name(self, name: str) -> None:
        """名前を設定する"""  # メソッド名と同じ
        self.name = name
 
    def is_active(self) -> bool:
        """アクティブかどうかを返す"""  # メソッド名の翻訳
        return self.status == Status.ACTIVE

# BEFORE: コメントで各セクションを説明
def process_order(order: Order) -> OrderResult:
    # バリデーション
    if not order.items:
        raise ValidationError("商品が選択されていません")
    if not order.customer_id:
        raise ValidationError("顧客情報がありません")
    for item in order.items:
        if item.quantity <= 0:
            raise ValidationError(f"数量が不正: {item.name}")
 
    # 合計計算
    subtotal = sum(item.price * item.quantity for item in order.items)
    tax = subtotal * Decimal("0.10")
    shipping = Decimal("500") if subtotal < Decimal("5000") else Decimal("0")
    total = subtotal + tax + shipping
 
    # 保存
    order.total = total
    db.save(order)
 
    # 通知
    email_service.send_confirmation(order)
 
    return OrderResult.success(order)
 
 
# AFTER: 関数名がコメントの代わりになる
def process_order(order: Order) -> OrderResult:
    validate_order(order)
    pricing = calculate_order_pricing(order)
    saved_order = save_order(order, pricing)
    send_order_confirmation(saved_order)
    return OrderResult.success(saved_order)
 
def validate_order(order: Order) -> None:
    """注文の入力値を検証する。"""
    if not order.items:
        raise ValidationError("商品が選択されていません")
    if not order.customer_id:
        raise ValidationError("顧客情報がありません")
    for item in order.items:
        if item.quantity <= 0:
            raise ValidationError(f"数量が不正: {item.name}")
 
def calculate_order_pricing(order: Order) -> OrderPricing:
    """注文の価格情報を算出する。"""
    subtotal = sum(item.price * item.quantity for item in order.items)
    tax = subtotal * TAX_RATE
    shipping = calculate_shipping_fee(subtotal)
    return OrderPricing(subtotal=subtotal, tax=tax, shipping=shipping)
 
FREE_SHIPPING_THRESHOLD = Decimal("5000")
STANDARD_SHIPPING_FEE = Decimal("500")
 
def calculate_shipping_fee(subtotal: Decimal) -> Decimal:
    """小計に基づいて送料を算出する。"""
    if subtotal >= FREE_SHIPPING_THRESHOLD:
        return Decimal("0")
    return STANDARD_SHIPPING_FEE

# BEFORE: マジックナンバーにコメント
def check_password(password: str) -> bool:
    if len(password) < 8:      # 最小文字数
        return False
    if len(password) > 128:    # 最大文字数
        return False
    if not re.search(r'[A-Z]', password):  # 大文字必須
        return False
    if not re.search(r'[0-9]', password):  # 数字必須
        return False
    return True
 
 
# AFTER: 定数名が説明する
MIN_PASSWORD_LENGTH = 8
MAX_PASSWORD_LENGTH = 128
UPPERCASE_PATTERN = re.compile(r'[A-Z]')
DIGIT_PATTERN = re.compile(r'[0-9]')
 
def check_password(password: str) -> bool:
    if len(password) < MIN_PASSWORD_LENGTH:
        return False
    if len(password) > MAX_PASSWORD_LENGTH:
        return False
    if not UPPERCASE_PATTERN.search(password):
        return False
    if not DIGIT_PATTERN.search(password):
        return False
    return True

# BEFORE: 複雑な条件にコメント
def should_send_reminder(user: User, order: Order) -> bool:
    # プレミアム以上のアクティブユーザーで、
    # 最終注文から30日以上経過し、
    # 通知設定がオンの場合にリマインダーを送る
    return (user.tier in ('premium', 'enterprise')
            and user.status == 'active'
            and (datetime.now() - order.last_order_date).days > 30
            and user.notification_enabled)
 
 
# AFTER: 説明用変数で条件の意図を表現
INACTIVITY_THRESHOLD_DAYS = 30
 
def should_send_reminder(user: User, order: Order) -> bool:
    is_high_tier_user = user.tier in ('premium', 'enterprise')
    is_active = user.status == 'active'
    days_since_last_order = (datetime.now() - order.last_order_date).days
    is_inactive_buyer = days_since_last_order > INACTIVITY_THRESHOLD_DAYS
    accepts_notifications = user.notification_enabled
 
    return (is_high_tier_user
            and is_active
            and is_inactive_buyer
            and accepts_notifications)

# BEFORE: コメントで型の意味を補足
def create_user(
    name: str,       # ユーザー名（2-50文字）
    email: str,      # メールアドレス（RFC 5322準拠）
    age: int,        # 年齢（0-150）
    role: str,       # ロール（"admin", "user", "viewer"）
) -> dict:           # ユーザー情報辞書
    pass
 
 
# AFTER: 型がドキュメントになる
class UserName:
    """2-50文字のユーザー名を表す値オブジェクト。"""
    def __init__(self, value: str):
        if not (2 <= len(value) <= 50):
            raise ValueError(f"ユーザー名は2-50文字: {len(value)}文字")
        self.value = value
 
class Email:
    """RFC 5322準拠のメールアドレスを表す値オブジェクト。"""
    def __init__(self, value: str):
        if not EMAIL_PATTERN.match(value):
            raise ValueError(f"不正なメールアドレス: {value}")
        self.value = value
 
class Age:
    """0-150の年齢を表す値オブジェクト。"""
    def __init__(self, value: int):
        if not (0 <= value <= 150):
            raise ValueError(f"不正な年齢: {value}")
        self.value = value
 
class Role(Enum):
    ADMIN = "admin"
    USER = "user"
    VIEWER = "viewer"
 
@dataclass
class User:
    name: UserName
    email: Email
    age: Age
    role: Role
 
def create_user(name: UserName, email: Email, age: Age, role: Role) -> User:
    # コメント不要 ── 型が全てを語る
    return User(name=name, email=email, age=age, role=role)

# BEFORE: 深いネスト + コメントで条件を説明
def calculate_discount(order: Order) -> Decimal:
    # 注文が空の場合は割引なし
    if order.items:
        # プレミアム会員の場合
        if order.customer.is_premium:
            # 合計が1万円以上の場合は15%割引
            if order.total >= 10000:
                return order.total * Decimal("0.15")
            # それ以外は10%割引
            else:
                return order.total * Decimal("0.10")
        # 一般会員の場合
        else:
            # 合計が1万円以上の場合は5%割引
            if order.total >= 10000:
                return order.total * Decimal("0.05")
    return Decimal("0")
 
 
# AFTER: ガード節 + 意味のある定数で自明にする
PREMIUM_HIGH_DISCOUNT_RATE = Decimal("0.15")
PREMIUM_BASE_DISCOUNT_RATE = Decimal("0.10")
STANDARD_DISCOUNT_RATE = Decimal("0.05")
DISCOUNT_THRESHOLD = Decimal("10000")
 
def calculate_discount(order: Order) -> Decimal:
    if not order.items:
        return Decimal("0")
 
    if not order.customer.is_premium:
        if order.total >= DISCOUNT_THRESHOLD:
            return order.total * STANDARD_DISCOUNT_RATE
        return Decimal("0")
 
    if order.total >= DISCOUNT_THRESHOLD:
        return order.total * PREMIUM_HIGH_DISCOUNT_RATE
    return order.total * PREMIUM_BASE_DISCOUNT_RATE

def transfer_funds(
    source: Account,
    destination: Account,
    amount: Decimal,
    currency: Currency = Currency.JPY
) -> TransferReceipt:
    """指定された金額を送金元から送金先に振り替える。
 
    同一通貨間の即時振替を実行する。異なる通貨間の
    振替は未対応（CurrencyMismatchError を送出）。
 
    トランザクション分離レベルは SERIALIZABLE で実行される。
    ネットワーク障害時のリトライは呼び出し側で行うこと。
 
    Args:
        source: 送金元口座。残高が amount 以上必要。
        destination: 送金先口座。凍結されていないこと。
        amount: 振替金額。正の数であること。
        currency: 通貨。デフォルトは日本円。
 
    Returns:
        TransferReceipt: 取引IDとタイムスタンプを含む受領証。
 
    Raises:
        InsufficientBalanceError: 送金元の残高不足。
        AccountFrozenError: いずれかの口座が凍結されている。
        CurrencyMismatchError: 口座の通貨と指定通貨が不一致。
        ValueError: amount が 0 以下の場合。
 
    Example:
        >>> receipt = transfer_funds(account_a, account_b, Decimal('10000'))
        >>> print(receipt.transaction_id)
        'TXN-20240101-001'
        >>> print(receipt.timestamp)
        datetime(2024, 1, 1, 12, 0, 0)
 
    Note:
        同一口座間の振替は InsufficientBalanceError を送出する。
        これはビジネスルールによる制約である。
 
    See Also:
        - `Account.withdraw`: 口座からの引き出し
        - `Account.deposit`: 口座への入金
        - `TransferReceipt`: 受領証の詳細
    """

/**
 * 商品の在庫数を更新する。
 *
 * <p>在庫数の更新は楽観的ロックを使用して排他制御を行う。
 * 同時更新が発生した場合は {@link OptimisticLockException} がスローされる。</p>
 *
 * <p>在庫数が0以下になる更新はビジネスルールにより拒否される。</p>
 *
 * @param productId 商品ID（null不可）
 * @param delta     在庫変動数（正: 入庫、負: 出庫）
 * @return 更新後の在庫数
 * @throws ProductNotFoundException 商品IDが存在しない場合
 * @throws InsufficientStockException 在庫が不足して出庫できない場合
 * @throws OptimisticLockException 同時更新が検出された場合
 * @since 2.0
 * @see Product#getStockCount()
 */
public int updateStock(String productId, int delta) {
    // ...
}

/**
 * ユーザーの認証トークンを検証する。
 *
 * @remarks
 * JWTの署名検証、有効期限チェック、リボケーションチェックを行う。
 * トークンが有効な場合は復号化されたペイロードを返す。
 *
 * @param token - JWT形式の認証トークン
 * @param options - 検証オプション
 * @returns 復号化されたトークンペイロード
 * @throws {@link TokenExpiredError} トークンの有効期限が切れている場合
 * @throws {@link InvalidSignatureError} 署名が不正な場合
 * @throws {@link RevokedTokenError} トークンが無効化されている場合
 *
 * @example
 * ```typescript
 * const payload = await verifyToken("eyJhbGci...", {
 *   audience: "my-app",
 *   issuer: "auth-server",
 * });
 * console.log(payload.userId); // "user-123"
 * ```
 */
async function verifyToken(
  token: string,
  options?: VerifyOptions
): Promise<TokenPayload> {
  // ...
}

# ----- Google スタイル -----
def connect(host: str, port: int, timeout: float = 30.0) -> Connection:
    """サーバーに接続する。
 
    Args:
        host: サーバーのホスト名またはIPアドレス。
        port: ポート番号（1-65535）。
        timeout: 接続タイムアウト（秒）。
 
    Returns:
        確立された接続オブジェクト。
 
    Raises:
        ConnectionError: 接続に失敗した場合。
    """
 
# ----- NumPy スタイル -----
def connect(host: str, port: int, timeout: float = 30.0) -> Connection:
    """サーバーに接続する。
 
    Parameters
    ----------
    host : str
        サーバーのホスト名またはIPアドレス。
    port : int
        ポート番号（1-65535）。
    timeout : float, optional
        接続タイムアウト（秒）。デフォルトは30.0。
 
    Returns
    -------
    Connection
        確立された接続オブジェクト。
 
    Raises
    ------
    ConnectionError
        接続に失敗した場合。
    """
 
# ----- reStructuredText (Sphinx) スタイル -----
def connect(host: str, port: int, timeout: float = 30.0) -> Connection:
    """サーバーに接続する。
 
    :param host: サーバーのホスト名またはIPアドレス。
    :param port: ポート番号（1-65535）。
    :param timeout: 接続タイムアウト（秒）。
    :returns: 確立された接続オブジェクト。
    :raises ConnectionError: 接続に失敗した場合。
    """

# コメントポリシー (テンプレート)
 
## 基本方針
- コメントの言語: 日本語
- コードで意図を表現することを最優先する
- Why コメントを積極的に書く
- What コメントは原則不要
 
## 必須コメント
- 公開APIのドキュメンテーションコメント (Google スタイル)
- ライセンスヘッダー (SPDX 形式)
- 複雑なアルゴリズムの説明
- 非自明な設計判断の理由
 
## 禁止コメント
- コードの直訳コメント
- コメントアウトされたコード（Git を使うこと）
- 属人的な情報（個人名）
- ファイル内の変更履歴
 
## TODO コメント
- 形式: `# TODO(#<Issue番号>): <説明>`
- Issue トラッカーとの紐づけ必須
- 四半期ごとに棚卸しを実施
- CI で TODO 数を監視（閾値超過で警告）
 
## ドキュメンテーションコメント
- public メソッド/クラス: 必須
- protected メソッド: 推奨
- private メソッド: 名前で意図が不明な場合のみ
- スタイル: Google スタイル

# .github/workflows/comment-check.yml
name: Comment Quality Check
 
on: pull_request
 
jobs:
  check-comments:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Check for commented-out code blocks
        run: |
          # 3行以上連続するコメントアウトコードを検出
          python -c "
          import re, sys, pathlib
          pattern = re.compile(r'(^\s*#\s*(if|for|def|class|return|import|from)\b.*\n){3,}', re.MULTILINE)
          found = False
          for f in pathlib.Path('src').rglob('*.py'):
              text = f.read_text()
              if pattern.search(text):
                  print(f'WARNING: Possible commented-out code in {f}')
                  found = True
          sys.exit(1 if found else 0)
          "
 
      - name: Check TODO format
        run: |
          # Issue番号なしの TODO を検出
          if grep -rn 'TODO[^(]' --include="*.py" --include="*.ts" src/; then
            echo "ERROR: TODO without issue number found"
            echo "Required format: TODO(#<issue_number>): <description>"
            exit 1
          fi
 
      - name: Count TODOs
        run: |
          count=$(grep -rn 'TODO' --include="*.py" src/ | wc -l)
          echo "Current TODO count: $count"
          if [ "$count" -gt 50 ]; then
            echo "WARNING: TODO count exceeds threshold (50)"
          fi

# パターン1: セクションコメント → 関数抽出
# BEFORE
def process_data(raw_data):
    # データのクレンジング
    data = raw_data.strip()
    data = data.replace('\n', ' ')
    data = re.sub(r'\s+', ' ', data)
 
    # データの変換
    parts = data.split(',')
    result = [int(p) for p in parts if p.isdigit()]
 
    # データの検証
    if not result:
        raise ValueError("有効なデータがありません")
    if max(result) > 1000000:
        raise ValueError("値が範囲外です")
 
    return result
 
# AFTER: コメントが関数名になった
def process_data(raw_data: str) -> list[int]:
    cleaned = cleanse_whitespace(raw_data)
    integers = extract_integers(cleaned)
    validate_integer_range(integers)
    return integers
 
def cleanse_whitespace(raw_data: str) -> str:
    """空白文字を正規化する。"""
    data = raw_data.strip()
    data = data.replace('\n', ' ')
    return re.sub(r'\s+', ' ', data)
 
def extract_integers(data: str) -> list[int]:
    """カンマ区切り文字列から整数を抽出する。"""
    parts = data.split(',')
    return [int(p) for p in parts if p.isdigit()]
 
MAX_VALUE = 1_000_000
 
def validate_integer_range(data: list[int]) -> None:
    """整数リストが空でなく、値が範囲内であることを検証する。"""
    if not data:
        raise ValueError("有効なデータがありません")
    if max(data) > MAX_VALUE:
        raise ValueError(f"値が範囲外です (最大: {MAX_VALUE})")

// NG: 複雑なロジックをコメントで説明
// ステータスが1（アクティブ）で、タイプが3（プレミアム）または
// タイプが4（エンタープライズ）で、最終ログインが30日以内の場合
if (user.status == 1 && (user.type == 3 || user.type == 4)
    && daysSince(user.lastLogin) <= 30) {
    // ...
}
 
// OK: コード自体が意図を語る
if (user.isActive() && user.isPremiumOrAbove() && user.isRecentlyActive()) {
    // ...
}

# NG: ファイル内の変更履歴
# 変更履歴:
# 2024-01-01 田中: 初版作成
# 2024-02-15 佐藤: バリデーション追加
# → バージョン管理システム（Git）が担うべき役割

# NG: 公開 API にドキュメントがない
def search(q, opts=None):
    pass
 
# OK: 公開 API にはドキュメンテーションコメント必須
def search(
    query: str,
    options: SearchOptions | None = None,
) -> SearchResult:
    """全文検索を実行する。
 
    Elasticsearch のインデックスに対してクエリを実行し、
    関連度順にソートされた結果を返す。
 
    Args:
        query: 検索クエリ文字列。Lucene クエリ構文をサポート。
        options: 検索オプション（ページネーション、フィルタ等）。
 
    Returns:
        SearchResult: ヒット件数と検索結果のリスト。
 
    Raises:
        InvalidQueryError: クエリ構文が不正な場合。
        SearchTimeoutError: 検索がタイムアウトした場合（デフォルト30秒）。
    """

# NG: 古いコメントが放置されている
# 最大3回リトライする
MAX_RETRIES = 5  # 値は5に変更されたがコメントは未更新
 
# 月額料金を計算（消費税8%）
def calculate_monthly_fee(base_price: int) -> int:
    return int(base_price * 1.10)  # 税率は10%に変更済み
 
# OK: コメントが不要になるようコードを改善
MAX_RETRIES = 5  # コメント不要（定数名が自明）
 
TAX_RATE = Decimal("1.10")
 
def calculate_monthly_fee_with_tax(base_price: int) -> int:
    return int(base_price * TAX_RATE)

# ユーザーサービスクラス
class UserService:
    # コンストラクタ
    def __init__(self, repo, mailer):
        # リポジトリを設定
        self.repo = repo
        # メーラーを設定
        self.mailer = mailer
 
    # ユーザーを作成する
    def create_user(self, name, email):
        # 名前のバリデーション
        if not name:
            # 名前が空の場合はエラー
            raise ValueError("名前は必須です")
        # メールのバリデーション
        if not email:
            # メールが空の場合はエラー
            raise ValueError("メールは必須です")
 
        # ユーザーオブジェクトを作成
        user = User(name=name, email=email)
        # データベースに保存
        self.repo.save(user)
        # 確認メールを送信
        # ※ メール送信が失敗してもユーザー作成は成功扱い
        # ※ 非同期にすべきだが、現状のインフラでは同期のみ
        try:
            self.mailer.send_welcome(email)
        except MailError:
            pass  # TODO: ログに記録する
        # ユーザーを返す
        return user

class UserService:
    def __init__(self, repo: UserRepository, mailer: Mailer):
        self.repo = repo
        self.mailer = mailer
 
    def create_user(self, name: str, email: str) -> User:
        if not name:
            raise ValueError("名前は必須です")
        if not email:
            raise ValueError("メールは必須です")
 
        user = User(name=name, email=email)
        self.repo.save(user)
 
        # メール送信失敗はユーザー作成の成功に影響しない。
        # 理由: ウェルカムメールは再送可能であり、
        # ユーザー作成のトランザクションを巻き戻す必要がないため。
        # TODO(#567): 非同期メール送信への移行（インフラ対応待ち）
        try:
            self.mailer.send_welcome(email)
        except MailError:
            logger.warning(f"ウェルカムメール送信失敗: {email}")
 
        return user

def calc(data):
    result = []
    for item in data:
        # 有効期限が過ぎていないかチェック
        if item['exp'] >= datetime.now():
            # ステータスがアクティブかチェック
            if item['st'] == 1:
                # 金額に税率を掛ける
                amount = item['amt'] * 1.10
                # 会員の場合は5%割引
                if item['mbr']:
                    amount = amount * 0.95
                # 結果に追加
                result.append({
                    'id': item['id'],
                    'total': amount,
                    'name': item['nm']
                })
    return result

from dataclasses import dataclass
from datetime import datetime
from decimal import Decimal
 
TAX_RATE = Decimal("1.10")
MEMBER_DISCOUNT_RATE = Decimal("0.95")
 
@dataclass
class Item:
    id: str
    name: str
    amount: Decimal
    is_active: bool
    expiry_date: datetime
    is_member: bool
 
    def is_expired(self) -> bool:
        return self.expiry_date < datetime.now()
 
@dataclass
class PricedItem:
    id: str
    name: str
    total: Decimal
 
def calculate_priced_items(items: list[Item]) -> list[PricedItem]:
    return [
        price_item(item)
        for item in items
        if is_eligible(item)
    ]
 
def is_eligible(item: Item) -> bool:
    return not item.is_expired() and item.is_active
 
def price_item(item: Item) -> PricedItem:
    total = apply_tax(item.amount)
    if item.is_member:
        total = apply_member_discount(total)
    return PricedItem(id=item.id, name=item.name, total=total)
 
def apply_tax(amount: Decimal) -> Decimal:
    return amount * TAX_RATE
 
def apply_member_discount(amount: Decimal) -> Decimal:
    return amount * MEMBER_DISCOUNT_RATE

class CacheManager:
    def __init__(self, max_size, ttl_seconds, eviction_policy):
        self._store = {}
        self._max_size = max_size
        self._ttl = ttl_seconds
        self._policy = eviction_policy
 
    def get(self, key):
        pass
 
    def set(self, key, value, ttl=None):
        pass
 
    def invalidate(self, key):
        pass
 
    def clear(self):
        pass
 
    def stats(self):
        pass

class CacheManager:
    """インメモリキャッシュマネージャ。
 
    TTL（有効期限）付きのキーバリューキャッシュを提供する。
    最大サイズに達した場合、指定された退避ポリシーに基づいて
    エントリを退避する。
 
    スレッドセーフではない。マルチスレッド環境では
    外部で排他制御を行うか、ThreadSafeCacheManager を使用すること。
 
    Attributes:
        max_size: キャッシュの最大エントリ数。
        ttl_seconds: デフォルトの TTL（秒）。0 は無期限。
        eviction_policy: 退避ポリシー（"lru", "lfu", "fifo"）。
 
    Example:
        >>> cache = CacheManager(max_size=1000, ttl_seconds=300,
        ...                      eviction_policy="lru")
        >>> cache.set("user:123", {"name": "Alice"})
        >>> user = cache.get("user:123")
        >>> print(user)
        {"name": "Alice"}
        >>> print(cache.stats())
        CacheStats(hits=1, misses=0, size=1, hit_rate=1.0)
    """
 
    def get(self, key: str) -> Any | None:
        """キーに対応する値を取得する。
 
        TTL が切れているエントリは None を返し、内部から削除する。
 
        Args:
            key: キャッシュキー。
 
        Returns:
            キャッシュされた値。キーが存在しないか TTL 切れの場合は None。
        """
 
    def set(self, key: str, value: Any, ttl: int | None = None) -> None:
        """キーと値のペアをキャッシュに格納する。
 
        キャッシュが max_size に達している場合、eviction_policy に
        基づいて既存エントリを1つ退避してから格納する。
 
        Args:
            key: キャッシュキー。
            value: 格納する値。シリアライズ可能であること。
            ttl: このエントリの TTL（秒）。None の場合はデフォルト TTL を使用。
 
        Raises:
            ValueError: ttl が負の数の場合。
        """
 
    def invalidate(self, key: str) -> bool:
        """指定されたキーのエントリを無効化（削除）する。
 
        Args:
            key: 無効化するキャッシュキー。
 
        Returns:
            キーが存在して削除された場合は True、存在しない場合は False。
        """
 
    def clear(self) -> None:
        """全てのキャッシュエントリを削除する。
 
        統計情報もリセットされる。
        """
 
    def stats(self) -> CacheStats:
        """キャッシュの統計情報を取得する。
 
        Returns:
            CacheStats: ヒット数、ミス数、現在のサイズ、ヒット率を含む統計。
        """