# === 悪い命名: 何のデータか分からない ===
d = 86400
l = get_list()
for i in l:
    if i.s == 1:
        process(i)
 
# 読み手の疑問:
# - d は何の数値？ → 1日の秒数？定数？
# - l は何のリスト？ → ユーザー？注文？
# - i.s は何？ → status? score? size?
# - 1 は何を意味する？ → アクティブ？完了？
 
 
# === 良い命名: コードが自己説明的 ===
SECONDS_PER_DAY = 86400
active_users = get_active_users()
for user in active_users:
    if user.status == UserStatus.ACTIVE:
        send_notification(user)
 
# 読み手は即座に理解:
# - 1日の秒数を定数として定義
# - アクティブユーザーのリストを取得
# - 各ユーザーのステータスがアクティブなら通知を送信

# ============================================================
# ルール: スコープが広いほど名前は長く、狭いほど短くてよい
# ============================================================
 
# ループ変数（短いスコープ）: 短い名前でOK
for i in range(10):
    matrix[i][i] = 1
 
# ただし意味がある場合は明示する
for row_index in range(height):
    for col_index in range(width):
        grid[row_index][col_index] = calculate_cell(row_index, col_index)
 
# モジュールレベル定数（長いスコープ）: 長くて具体的に
MAX_LOGIN_ATTEMPTS_BEFORE_LOCKOUT = 5
DEFAULT_SESSION_TIMEOUT_MINUTES = 30
MINIMUM_PASSWORD_LENGTH = 8
 
# クラスメンバー（中程度のスコープ）: 適度な長さ
class UserService:
    def __init__(self):
        self.retry_count = 0            # クラス内でのコンテキストがある
        self.last_login_timestamp = None  # クラス名が文脈を提供
 
# グローバルに近い変数: 最も具体的に
user_session_timeout_seconds = 1800
database_connection_pool_max_size = 20

// === 悪い: trueの意味が不明 ===
let flag = true;
let check = false;
let status = true;
let enable = false;
let login = true;
 
// === 良い: true/falseの意味が明確 ===
let isVisible = true;
let hasAdminPermission = false;
let shouldAutoSave = true;
let canDeletePost = user.role === 'admin';
let wasProcessed = order.processedAt !== null;
let isEmailVerified = !!user.emailVerifiedAt;
let hasExceededLimit = currentCount > MAX_ALLOWED;
 
// ブール変数命名のベストプラクティス
// | プレフィックス | 意味           | 例                     |
// |-------------|---------------|------------------------|
// | is          | 状態である     | isActive, isLoading    |
// | has         | 持っている     | hasError, hasChildren  |
// | can         | 可能である     | canEdit, canDelete     |
// | should      | すべきである   | shouldUpdate, shouldRetry |
// | was         | 過去の状態     | wasDeleted, wasNotified |
// | will        | 未来の状態     | willExpire, willRetry  |

# === 悪い: 単位が不明 ===
timeout = 5000     # ミリ秒？秒？分？
file_size = 1024   # バイト？KB？MB？
distance = 100     # メートル？キロメートル？マイル？
age = 25           # 年？月？日？
 
# === 良い: 単位を名前に含める ===
timeout_ms = 5000
timeout_seconds = 5
file_size_bytes = 1048576
file_size_mb = 1.0
distance_km = 100.0
age_years = 25
 
# === さらに良い: 型で単位を表現（型安全） ===
from dataclasses import dataclass
 
@dataclass
class Duration:
    milliseconds: int
 
    @classmethod
    def from_seconds(cls, seconds: int) -> 'Duration':
        return cls(milliseconds=seconds * 1000)
 
    @classmethod
    def from_minutes(cls, minutes: int) -> 'Duration':
        return cls(milliseconds=minutes * 60 * 1000)
 
# 使用例
connection_timeout = Duration.from_seconds(30)
session_timeout = Duration.from_minutes(15)

// get: 既にメモリにある、または即座に取得可能なもの
class User {
  getName(): string { return this.name; }        // フィールドアクセス
  getAge(): number { return calculateAge(this.birthDate); } // 計算
}
 
// fetch: 外部リソース（API、DB）から非同期取得
async function fetchUserFromAPI(id: string): Promise<User> {
  return await api.get(`/users/${id}`);
}
 
// find: 検索（見つからない可能性がある → Optional/null を返す）
function findUserByEmail(email: string): User | undefined {
  return users.find(u => u.email === email);
}
 
// 混同すると危険な例
class UserService {
  // 悪い: getUser がDBアクセスするなら fetch の方が適切
  async getUser(id: string): Promise<User> {
    return await this.db.query('SELECT * FROM users WHERE id = ?', [id]);
  }
 
  // 良い: 非同期外部取得であることが名前から分かる
  async fetchUser(id: string): Promise<User> {
    return await this.db.query('SELECT * FROM users WHERE id = ?', [id]);
  }
}

# === 悪い: 何をする関数か分からない ===
def handle(data):
    pass
 
def do_it(x, y):
    pass
 
def process(items):
    pass
 
def run(config):
    pass
 
def execute(params):
    pass
 
# === 良い: 動詞+名詞で動作と対象を明示 ===
def validate_email_format(email: str) -> bool:
    """メールアドレスの形式を検証する"""
    pass
 
def calculate_monthly_revenue(transactions: list[Transaction]) -> Decimal:
    """月次売上を計算する"""
    pass
 
def send_password_reset_email(user: User) -> None:
    """パスワードリセットメールを送信する"""
    pass
 
def convert_celsius_to_fahrenheit(celsius: float) -> float:
    """摂氏を華氏に変換する"""
    return celsius * 9 / 5 + 32
 
def find_expired_subscriptions(cutoff_date: date) -> list[Subscription]:
    """期限切れのサブスクリプションを検索する"""
    pass

// === 悪い: プレフィックスで名前空間を代用 ===
class AppUserAccountValidationService { }
class AppUserAccountRepository { }
class AppUserAccountDTO { }
// → 名前が長すぎて可読性が低い
 
// === 良い: パッケージ/モジュールで名前空間を構成 ===
package com.example.user.account;
 
class ValidationService { }
class Repository { }
class AccountDTO { }
 
// 使用時: 文脈から意味が明確
import com.example.user.account.ValidationService;
// → パッケージが文脈を提供するので、クラス名を短くできる

// === 定数: マジックナンバーに意味のある名前をつける ===
 
// 悪い: マジックナンバー
if (password.length < 8) { ... }
if (retryCount > 3) { ... }
if (status === 2) { ... }
 
// 良い: 意図が明確な定数
const MINIMUM_PASSWORD_LENGTH = 8;
const MAX_RETRY_ATTEMPTS = 3;
 
if (password.length < MINIMUM_PASSWORD_LENGTH) { ... }
if (retryCount > MAX_RETRY_ATTEMPTS) { ... }
 
// === 列挙型: 選択肢の集合に名前をつける ===
 
// 悪い: 文字列リテラルで状態を管理
let status = 'active';
if (status === 'active' || status === 'pending') { ... }
// → タイポに気づけない、補完が効かない
 
// 良い: 列挙型で型安全に
enum OrderStatus {
  PENDING = 'pending',
  CONFIRMED = 'confirmed',
  SHIPPED = 'shipped',
  DELIVERED = 'delivered',
  CANCELLED = 'cancelled',
}
 
enum UserRole {
  ADMIN = 'admin',
  EDITOR = 'editor',
  VIEWER = 'viewer',
}
 
// 使用
if (order.status === OrderStatus.PENDING || order.status === OrderStatus.CONFIRMED) {
  // タイポがコンパイルエラーで検出される
}

# === 悪い: 同じ概念に異なる名前を使う ===
 
# ファイル1: user_controller.py
def get_client(client_id):  # "client" と呼んでいる
    pass
 
# ファイル2: order_service.py
def create_order(customer_id):  # "customer" と呼んでいる
    pass
 
# ファイル3: notification.py
def notify_user(user_id):  # "user" と呼んでいる
    pass
 
# → "client", "customer", "user" は同じ概念？異なる概念？混乱を招く
 
 
# === 良い: 用語集（Glossary）を定義して統一 ===
 
# 用語集:
# - User: システムにログインする人
# - Customer: 商品を購入する人（User の一種）
# - Guest: ログインしていない訪問者
 
# ファイル1: user_controller.py
def get_user(user_id):  # 統一された用語
    pass
 
# ファイル2: order_service.py
def create_order(customer_id):  # Customer は User の特殊な役割
    pass
 
# ファイル3: notification.py
def notify_user(user_id):  # 統一された用語
    pass

// === 悪い: コンテキストの冗長な繰り返し ===
class User {
  userName: string;        // "User" が冗長
  userEmail: string;       // "User" が冗長
  userAge: number;         // "User" が冗長
  userAddress: Address;    // "User" が冗長
 
  getUserName(): string { return this.userName; }
  setUserEmail(email: string): void { this.userEmail = email; }
}
 
// === 良い: クラスがコンテキストを提供 ===
class User {
  name: string;            // User.name で十分に明確
  email: string;           // User.email で十分に明確
  age: number;             // User.age で十分に明確
  address: Address;        // User.address で十分に明確
 
  getName(): string { return this.name; }
  setEmail(email: string): void { this.email = email; }
}
 
// === ただし、コンテキストの外では具体的に ===
// 関数の引数としてクラスの外に出る場合は具体的にする
function sendEmail(recipientEmail: string, senderEmail: string): void {
  // "email" だけでは sender か recipient か不明
}

# === Python の命名慣習 ===
# PEP 8 に従う
 
# モジュールレベル定数
MAX_RETRY_COUNT = 3
DEFAULT_TIMEOUT_SECONDS = 30
 
# 関数と変数: snake_case
def calculate_total_price(items: list[OrderItem]) -> Decimal:
    subtotal = sum(item.price * item.quantity for item in items)
    return subtotal
 
# クラス: PascalCase
class OrderProcessor:
    # プライベート: _single_leading_underscore
    def _validate_order(self, order: Order) -> bool:
        pass
 
    # 名前マングリング: __double_leading_underscore（極めて稀に使用）
    def __internal_state(self):
        pass
 
    # ダンダーメソッド: __name__（Pythonの特殊メソッド）
    def __str__(self) -> str:
        pass

// === Go の命名慣習 ===
// Go は大文字/小文字で公開/非公開を区別する
 
// 公開: CamelCase（大文字始まり）
func CalculateTax(amount float64) float64 {
    return amount * taxRate
}
 
// 非公開: camelCase（小文字始まり）
func calculateDiscount(amount float64) float64 {
    return amount * discountRate
}
 
// インターフェース: 動詞+er
type Reader interface {
    Read(p []byte) (n int, err error)
}
 
type Writer interface {
    Write(p []byte) (n int, err error)
}
 
// 1メソッドのインターフェースは Doer 形式
type Stringer interface {
    String() string
}

// === TypeScript の命名慣習 ===
 
// インターフェース: PascalCase（I プレフィックスは賛否あり）
interface PaymentGateway {
  charge(amount: number): Promise<PaymentResult>;
}
 
// 型エイリアス: PascalCase
type UserId = string;
type OrderStatus = 'pending' | 'confirmed' | 'shipped';
 
// 列挙型: PascalCase（メンバーもPascalCase）
enum HttpStatus {
  Ok = 200,
  NotFound = 404,
  InternalServerError = 500,
}
 
// ジェネリクス: 単一文字 or 意味のある名前
function identity<T>(value: T): T { return value; }
function mapArray<TInput, TOutput>(
  items: TInput[],
  transform: (item: TInput) => TOutput
): TOutput[] {
  return items.map(transform);
}

# Step 1: 動くコードを書く（仮名でもOK）
def proc(d):
    r = []
    for x in d:
        if x > 0:
            r.append(x * 2)
    return r
 
# Step 2: 意図が分かったらリネーム（IDE: Shift+F6 / F2）
def double_positive_numbers(numbers: list[float]) -> list[float]:
    doubled = []
    for number in numbers:
        if number > 0:
            doubled.append(number * 2)
    return doubled
 
# Step 3: Pythonic に洗練
def double_positive_numbers(numbers: list[float]) -> list[float]:
    return [n * 2 for n in numbers if n > 0]

// NG: 型をプレフィックスに入れる（現代のIDEでは不要）
let strName: string = "太郎";
let intAge: number = 25;
let arrUsers: User[] = [];
let bIsActive: boolean = true;
let objConfig: Config = {};
 
// OK: 型情報は型システムに任せる
let name: string = "太郎";
let age: number = 25;
let users: User[] = [];
let isActive: boolean = true;
let config: Config = {};
 
// 例外: UI系でのプレフィックスは許容される場合がある
// btnSubmit, txtEmail, lblError はUI要素の種類を示す

# NG: 解読が必要な名前
def calc_ttl_w_dsc(itms, dsc_pct):
    ttl = 0
    for itm in itms:
        ttl += itm.prc * itm.qty
    return ttl * (1 - dsc_pct / 100)
 
# OK: 省略せずフルスペルで
def calculate_total_with_discount(
    items: list[OrderItem],
    discount_percent: float
) -> float:
    subtotal = sum(item.price * item.quantity for item in items)
    return subtotal * (1 - discount_percent / 100)

# NG: 何でも意味が通ってしまう曖昧な名前
data = get_data()           # 何のデータ？
result = process(data)      # 何の結果？
info = fetch_info()         # 何の情報？
manager = get_manager()     # 何を管理？
handler = create_handler()  # 何をハンドル？
temp = calculate()          # 何の一時値？
 
# OK: 具体的な名前
user_profiles = fetch_active_user_profiles()
monthly_revenue = calculate_monthly_revenue(transactions)
server_health_info = check_server_health()
connection_manager = create_database_connection_pool()
request_handler = create_api_request_handler()
interpolated_value = interpolate_between(start, end, ratio)

def f(l, n):
    r = []
    for i in l:
        if i.a > n:
            r.append(i)
    return r
 
d = f(get_all(), 18)
for i in d:
    s(i.e, "Welcome!")

def find_users_older_than(users: list[User], minimum_age: int) -> list[User]:
    eligible_users = []
    for user in users:
        if user.age > minimum_age:
            eligible_users.append(user)
    return eligible_users
 
# さらにPythonic に
def find_users_older_than(users: list[User], minimum_age: int) -> list[User]:
    return [user for user in users if user.age > minimum_age]
 
adult_users = find_users_older_than(get_all_users(), minimum_age=18)
for user in adult_users:
    send_email(user.email, "Welcome!")

// user_controller.ts
function getClient(clientId: string): Client { ... }
function updateCustomerProfile(customerId: string, data: any): void { ... }
 
// notification_service.ts
function notifyMember(memberId: string, message: string): void { ... }
 
// billing_service.ts
function chargeAccount(accountHolderId: string, amount: number): void { ... }
 
// analytics_service.ts
function trackUserAction(userId: string, action: string): void { ... }

// 用語集を定義:
// - User: システムの利用者（統一された用語）
// - UserProfile: ユーザーのプロフィール情報
// - Account: 課金対象のアカウント
 
// user_controller.ts
function getUser(userId: string): User { ... }
function updateUserProfile(userId: string, profile: UserProfileUpdate): void { ... }
 
// notification_service.ts
function notifyUser(userId: string, message: string): void { ... }
 
// billing_service.ts
function chargeUserAccount(userId: string, amount: number): void { ... }
 
// analytics_service.ts
function trackUserAction(userId: string, action: string): void { ... }

# 命名規約
 
## 1. ブール変数
- プレフィックス: is, has, can, should, was, will
- 例: isActive, hasPermission, canEdit, shouldRetry
 
## 2. 非同期関数
- 外部API呼び出し: fetch + 名詞 (fetchUsers, fetchOrderById)
- DB操作: find/save/delete + 名詞 (findUserByEmail, saveOrder)
- 処理: process/handle + 名詞 + Async (processPaymentAsync)
 
## 3. エラー型
- 基底: AppError
- パターン: [名詞] + Error (ValidationError, NotFoundError)
- HTTP関連: Http + [ステータス] + Error (HttpNotFoundError)
 
## 4. APIエンドポイント
- RESTful: /api/v1/{resource}/{id}
- コレクション: 複数形 (/users, /orders)
- アクション: POST /api/v1/orders/{id}/cancel

# デバッグ用ユーティリティ
import logging
import traceback
from functools import wraps
 
# ロガーの設定
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s [%(levelname)s] %(name)s: %(message)s'
)
logger = logging.getLogger(__name__)
 
def debug_decorator(func):
    """関数の入出力をログ出力するデコレータ"""
    @wraps(func)
    def wrapper(*args, **kwargs):
        logger.debug(f"呼び出し: {func.__name__}(args={args}, kwargs={kwargs})")
        try:
            result = func(*args, **kwargs)
            logger.debug(f"戻り値: {func.__name__} -> {result}")
            return result
        except Exception as e:
            logger.error(f"例外発生: {func.__name__}: {e}")
            logger.error(traceback.format_exc())
            raise
    return wrapper
 
@debug_decorator
def process_data(items):
    """データ処理（デバッグ対象）"""
    if not items:
        raise ValueError("空のデータ")
    return [item * 2 for item in items]

# 設計判断の記録テンプレート
class ArchitectureDecisionRecord:
    """ADR (Architecture Decision Record) の作成"""
 
    def __init__(self, title: str):
        self.title = title
        self.context = ""
        self.decision = ""
        self.consequences = []
        self.alternatives = []
 
    def set_context(self, context: str):
        """背景と課題の記述"""
        self.context = context
        return self
 
    def set_decision(self, decision: str):
        """決定内容の記述"""
        self.decision = decision
        return self
 
    def add_consequence(self, consequence: str, positive: bool = True):
        """結果の追加"""
        self.consequences.append({
            'description': consequence,
            'type': 'positive' if positive else 'negative'
        })
        return self
 
    def add_alternative(self, name: str, reason_rejected: str):
        """却下した代替案の追加"""
        self.alternatives.append({
            'name': name,
            'reason_rejected': reason_rejected
        })
        return self
 
    def to_markdown(self) -> str:
        """Markdown形式で出力"""
        md = f"# ADR: {self.title}\n\n"
        md += f"## 背景\n{self.context}\n\n"
        md += f"## 決定\n{self.decision}\n\n"
        md += "## 結果\n"
        for c in self.consequences:
            icon = "✅" if c['type'] == 'positive' else "⚠️"
            md += f"- {icon} {c['description']}\n"
        md += "\n## 却下した代替案\n"
        for a in self.alternatives:
            md += f"- **{a['name']}**: {a['reason_rejected']}\n"
        return md

# チーム間のAPI契約定義
from dataclasses import dataclass
from typing import List, Optional
from enum import Enum
 
class Priority(Enum):
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"
    CRITICAL = "critical"
 
@dataclass
class APIContract:
    """チーム間のAPI契約"""
    endpoint: str
    method: str
    owner_team: str
    consumers: List[str]
    sla_ms: int  # レスポンスタイムSLA
    priority: Priority
 
    def validate_sla(self, actual_ms: int) -> bool:
        """SLA準拠の確認"""
        return actual_ms <= self.sla_ms
 
    def to_openapi(self) -> dict:
        """OpenAPI形式で出力"""
        return {
            'path': self.endpoint,
            'method': self.method,
            'x-owner': self.owner_team,
            'x-consumers': self.consumers,
            'x-sla-ms': self.sla_ms
        }
 
# 使用例
contracts = [
    APIContract(
        endpoint="/api/v1/users",
        method="GET",
        owner_team="user-team",
        consumers=["order-team", "notification-team"],
        sla_ms=200,
        priority=Priority.HIGH
    ),
    APIContract(
        endpoint="/api/v1/orders",
        method="POST",
        owner_team="order-team",
        consumers=["payment-team", "inventory-team"],
        sla_ms=500,
        priority=Priority.CRITICAL
    )
]

# セキュアコーディング例
import hashlib
import secrets
import hmac
from typing import Optional
 
class SecurityUtils:
    """セキュリティユーティリティ"""
 
    @staticmethod
    def generate_token(length: int = 32) -> str:
        """暗号学的に安全なトークン生成"""
        return secrets.token_urlsafe(length)
 
    @staticmethod
    def hash_password(password: str, salt: Optional[str] = None) -> tuple:
        """パスワードのハッシュ化"""
        if salt is None:
            salt = secrets.token_hex(16)
        hashed = hashlib.pbkdf2_hmac(
            'sha256',
            password.encode('utf-8'),
            salt.encode('utf-8'),
            iterations=100000
        )
        return hashed.hex(), salt
 
    @staticmethod
    def verify_password(password: str, hashed: str, salt: str) -> bool:
        """パスワードの検証"""
        new_hash, _ = SecurityUtils.hash_password(password, salt)
        return hmac.compare_digest(new_hash, hashed)
 
    @staticmethod
    def sanitize_input(value: str) -> str:
        """入力値のサニタイズ"""
        dangerous_chars = ['<', '>', '"', "'", '&', '\\']
        result = value
        for char in dangerous_chars:
            result = result.replace(char, '')
        return result.strip()
 
# 使用例
token = SecurityUtils.generate_token()
hashed, salt = SecurityUtils.hash_password("my_password")
is_valid = SecurityUtils.verify_password("my_password", hashed, salt)

# マイグレーションスクリプトのテンプレート
import json
import logging
from pathlib import Path
from datetime import datetime
from typing import List, Dict, Callable
 
logger = logging.getLogger(__name__)
 
class MigrationRunner:
    """段階的マイグレーション実行エンジン"""
 
    def __init__(self, migration_dir: str):
        self.migration_dir = Path(migration_dir)
        self.migrations: List[Dict] = []
        self.completed: List[str] = []
 
    def register(self, version: str, description: str,
                 up: Callable, down: Callable):
        """マイグレーションの登録"""
        self.migrations.append({
            'version': version,
            'description': description,
            'up': up,
            'down': down,
            'registered_at': datetime.now().isoformat()
        })
 
    def run_up(self, target_version: str = None):
        """マイグレーションの実行（アップグレード）"""
        for migration in self.migrations:
            if migration['version'] in self.completed:
                continue
            logger.info(f"実行中: {migration['version']} - "
                       f"{migration['description']}")
            try:
                migration['up']()
                self.completed.append(migration['version'])
                logger.info(f"完了: {migration['version']}")
            except Exception as e:
                logger.error(f"失敗: {migration['version']}: {e}")
                raise
            if target_version and migration['version'] == target_version:
                break
 
    def run_down(self, target_version: str):
        """マイグレーションのロールバック"""
        for migration in reversed(self.migrations):
            if migration['version'] not in self.completed:
                continue
            if migration['version'] == target_version:
                break
            logger.info(f"ロールバック: {migration['version']}")
            migration['down']()
            self.completed.remove(migration['version'])
 
    def status(self) -> Dict:
        """マイグレーション状態の確認"""
        return {
            'total': len(self.migrations),
            'completed': len(self.completed),
            'pending': len(self.migrations) - len(self.completed),
            'versions': {
                m['version']: 'completed'
                if m['version'] in self.completed else 'pending'
                for m in self.migrations
            }
        }

// get: 同期・軽量
function getUserName(user: User): string { return user.name; }
 
// fetch: 非同期・外部通信
async function fetchUserProfile(userId: string): Promise<UserProfile> {
  return await api.get(`/users/${userId}/profile`);
}
 
// find: 見つからない可能性あり
function findUserByEmail(email: string): User | null {
  return users.find(u => u.email === email) ?? null;
}

// パターン1: should + 期待動作 + when + 条件
it('should return empty array when no users match the criteria', () => { ... });
 
// パターン2: given-when-then をアンダースコアで区切る
test('given_expired_token_when_authenticate_then_throw_error', () => { ... });
 
// パターン3: メソッド名_条件_期待結果（xUnit スタイル）
test('calculateTotal_withDiscountCode_appliesDiscount', () => { ... });