coding-best-practices

Coding Best Practices Skill

Overview

このスキルは、Project Phantom での高品質なコード実装のためのベストプラクティスを提供します。Python を中心に、エラーハンドリング、API 呼び出し、ログ戦略、テスト手法をカバーします。

When to Use

• 新しいスクリプトや API を実装する時
• 既存コードのリファクタリング時
• コードレビューで品質を確認する時
• エラーハンドリングの改善が必要な時

Core Principles

1. Fail Fast, Fail Loudly

# ❌ Bad: Silent failure
def get_token():
    token = os.environ.get("API_TOKEN")
    return token  # None if not set

# ✅ Good: Explicit error
def get_token():
    token = os.environ.get("API_TOKEN")
    if not token:
        raise ValueError("API_TOKEN environment variable is not set")
    return token

2. Always Use Timeouts

# ❌ Bad: No timeout (can hang forever)
response = requests.get(url)

# ✅ Good: With timeout
response = requests.get(url, timeout=30)

3. Log Important Events

import logging

logger = logging.getLogger(__name__)

# Log at appropriate levels
logger.debug("Detailed debug information")
logger.info("High-level progress update")
logger.warning("Something unexpected but recoverable")
logger.error("Error occurred", exc_info=True)

Error Handling Patterns

HTTP API Calls

import requests
from typing import Optional, Dict, Any

def call_api(
    url: str,
    method: str = "GET",
    data: Optional[Dict[str, Any]] = None,
    headers: Optional[Dict[str, str]] = None
) -> Optional[Dict[str, Any]]:
    """
    Robust API call with comprehensive error handling.
    
    Args:
        url: The API endpoint
        method: HTTP method (GET, POST, etc.)
        data: Request payload
        headers: HTTP headers
    
    Returns:
        Response JSON or None on error
    """
    try:
        response = requests.request(
            method=method,
            url=url,
            json=data,
            headers=headers,
            timeout=30
        )
        
        # Check status code
        if response.status_code == 200:
            return response.json()
        elif response.status_code == 201:
            logger.info(f"Resource created: {url}")
            return response.json()
        elif response.status_code == 401:
            logger.error("Authentication failed. Check your token.")
            return None
        elif response.status_code == 403:
            logger.error("Permission denied. Check token scopes.")
            return None
        elif response.status_code == 404:
            logger.error(f"Resource not found: {url}")
            return None
        elif response.status_code == 422:
            logger.error(f"Validation error: {response.json()}")
            return None
        elif response.status_code >= 500:
            logger.error(f"Server error ({response.status_code}): {response.text}")
            return None
        else:
            logger.warning(f"Unexpected status {response.status_code}: {response.text}")
            return None
    
    except requests.exceptions.Timeout:
        logger.error(f"Request timeout: {url}")
        return None
    except requests.exceptions.ConnectionError:
        logger.error(f"Connection error: {url}")
        return None
    except requests.exceptions.RequestException as e:
        logger.error(f"Request failed: {e}", exc_info=True)
        return None
    except Exception as e:
        logger.error(f"Unexpected error: {e}", exc_info=True)
        return None