最小驚訝原則（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) { /* ... */ }
}

命名方法時，一致性至關重要。在這個糟糕的例子中，我們使用三個不同的動詞（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”方法不明確 - 它可能會添加一個新項目或更新一個現有項目。這個很好的例子將其分為兩個不同的方法，具有明確的名稱和目的。這使得程式碼的行為可預測，並遵循單一職責原則 (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中文網其他相關文章！