最小の驚きの原則 (POLA)

主要な概念

1. 一貫したメソッドの命名

// Bad - Inconsistent naming
class UserManager {
    public function getUser($id) { /* ... */ }
    public function fetchRole($id) { /* ... */ }
    public function retrievePermissions($id) { /* ... */ }
}

// Good - Consistent naming pattern
class UserManager {
    public function getUser($id) { /* ... */ }
    public function getRole($id) { /* ... */ }
    public function getPermissions($id) { /* ... */ }
}

メソッドに名前を付けるときは、一貫性が非常に重要です。悪い例では、同様の操作に 3 つの異なる動詞 (get、fetch、retrieve) を使用しています。そのため、開発者は同じ種類のアクションに対して異なる用語を覚えておく必要があります。良い例では、すべてのメソッドで一貫して「get」を使用しているため、API がより予測しやすく、覚えやすくなっています。開発者は、データにアクセスする必要がある場合、「get」で始まるメソッドを探す必要があることが直感的にわかります。

2. 期待される戻り値の型

// Bad - Unexpected return types
class FileHandler {
    public function readFile($path) {
        if (!file_exists($path)) {
            return false; // Unexpected boolean
        }
        return file_get_contents($path);
    }
}

// Good - Consistent return types with exceptions
class FileHandler {
    public function readFile($path): string {
        if (!file_exists($path)) {
            throw new FileNotFoundException("File not found: {$path}");
        }
        return file_get_contents($path);
    }
}

悪い例では戻り値の型が混在しており、文字列 (ファイルの内容) を返す場合もあれば、ブール値 (false) を返す場合もあります。これにより、戻り値の処理方法が不確実になります。良い例では、文字列の戻り値の型を宣言し、エラーの場合に例外を使用することで型の安全性を確保しています。これは PHP の組み込み動作と一致し、エラー処理がより明示的かつ予測可能になります。

3. 予測可能なパラメータの順序

// Bad - Inconsistent parameter order
class OrderProcessor {
    public function createOrder($items, $userId, $date) { /* ... */ }
    public function updateOrder($date, $orderId, $items) { /* ... */ }
}

// Good - Consistent parameter order
class OrderProcessor {
    public function createOrder($userId, $items, $date) { /* ... */ }
    public function updateOrder($orderId, $items, $date) { /* ... */ }
}

パラメータの順序は、同様のメソッド間で一貫している必要があります。悪い例では、同様のパラメータが異なる位置に配置されており、API が混乱しています。良い例では、論理的な順序が維持されています。最初に識別子 (userId/orderId)、次にメイン データ (項目)、そして最後にオプション/メタデータ パラメーター (日付) が続きます。このパターンは、PHP フレームワークの一般的な規則と一致し、API をより直感的にします。

4. 明確なメソッドの動作

// Bad - Ambiguous behavior
class Cart {
    public function add($product) {
        // Sometimes creates new item, sometimes updates quantity
        // Unpredictable!
    }
}

// Good - Clear, single responsibility
class Cart {
    public function addNewItem($product) { /* ... */ }
    public function updateQuantity($productId, $quantity) { /* ... */ }
}

メソッドには明確な単一の責任がある必要があります。悪い例の「add」メソッドはあいまいです。新しい項目を追加するか、既存の項目を更新する可能性があります。良い例では、これを明確な名前と目的を持つ 2 つの異なるメソッドに分割しています。これにより、コードの動作が予測可能になり、単一責任原則 (SRP) に従います。

5. 一貫したエラー処理

class PaymentProcessor {
    public function processPayment(float $amount): PaymentResult {
        try {
            // Process payment
            return new PaymentResult(true, 'Payment successful');
        } catch (PaymentException $e) {
            // Always handle errors the same way
            throw new PaymentFailedException($e->getMessage());
        }
    }
}

この例は、例外による一貫したエラー処理を示しています。何か問題が発生した場合、別のタイプを返したりエラー コードを使用したりする代わりに、常に特定の例外タイプ (PaymentFailedException) をスローします。これにより、アプリケーション全体でのエラー処理の予測可能なパターンが作成されます。このメソッドは、成功した場合に専用の PaymentResult オブジェクトも使用し、型の一貫性を維持します。

これらの各プラクティスは、PHP 開発の一般的なパターンと規則に基づいて開発者が期待する方法で動作するため、より保守しやすく、理解しやすく、バグが発生しにくいコードに貢献します。

以上が最小の驚きの原則 (POLA)の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。