Le principe du moindre étonnement (POLA)

Concepts clés

1. Dénomination cohérente des méthodes

// 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) { /* ... */ }
}

Lors de la dénomination des méthodes, la cohérence est cruciale. Dans le mauvais exemple, nous utilisons trois verbes différents (get, fetch, retrieve) pour des opérations similaires. Cela oblige les développeurs à mémoriser des termes différents pour le même type d'action. Le bon exemple utilise « get » de manière cohérente dans toutes les méthodes, ce qui rend l'API plus prévisible et plus facile à mémoriser. Lorsque les développeurs ont besoin d'accéder aux données, ils sauront intuitivement qu'il faut rechercher une méthode commençant par « get ».

2. Types de retours attendus

// 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);
    }
}

Le mauvais exemple mélange les types de retour - renvoyant parfois une chaîne (contenu du fichier) et parfois un booléen (faux). Cela crée une incertitude sur la manière de gérer la valeur de retour. Le bon exemple garantit la sécurité des types en déclarant un type de retour de chaîne et en utilisant des exceptions pour les cas d'erreur. Cela correspond au comportement intégré de PHP et rend la gestion des erreurs plus explicite et prévisible.

3. Ordre prévisible des paramètres

// 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) { /* ... */ }
}

L'ordre des paramètres doit être cohérent entre des méthodes similaires. Le mauvais exemple place des paramètres similaires dans des positions différentes, ce qui rend l'API déroutante. Le bon exemple maintient un ordre logique : l'identifiant en premier (userId/orderId), suivi des données principales (éléments) et des paramètres facultatifs/métadonnées en dernier (date). Ce modèle correspond aux conventions courantes dans les frameworks PHP et rend l'API plus intuitive.

4. Comportement clair de la méthode

// 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) { /* ... */ }
}

Les méthodes doivent avoir des responsabilités claires et uniques. La méthode « add » du mauvais exemple est ambiguë : elle peut ajouter un nouvel élément ou mettre à jour un élément existant. Le bon exemple divise cela en deux méthodes distinctes avec des noms et des objectifs clairs. Cela rend le comportement du code prévisible et suit le principe de responsabilité unique (SRP).

5. Gestion cohérente des erreurs

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());
        }
    }
}

Cet exemple démontre une gestion cohérente des erreurs via des exceptions. Au lieu de renvoyer différents types ou d'utiliser des codes d'erreur, il génère toujours un type d'exception spécifique (PaymentFailedException) en cas de problème. Cela crée un modèle prévisible pour la gestion des erreurs dans l’application. La méthode utilise également un objet PaymentResult dédié pour les cas réussis, en maintenant la cohérence des types.

Chacune de ces pratiques contribue à un code plus maintenable, plus facile à comprendre et moins sujet aux bogues, car il se comporte de la manière attendue par les développeurs, en fonction des modèles et des conventions courants dans le développement PHP.

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!