Règle
Utilisation nommé arguments pour clarté
Arguments nommés arguments rendent code auto-documentaire 
et empêcher paramètre ordre erreurs.
Utilisez nommés arguments lorsque fonctions ont plus
que 2-3 paramètres ou booléens drapeaux.

Langages pris en charge : Python, PHP

Introduction

Les fonctions avec plusieurs paramètres deviennent peu claires lorsqu'on examine l'appel. La lecture de sendEmail('user@example.com', true, false, 30) nécessite de rechercher la signature de la fonction pour comprendre ce que true, faux, et 30 signification. Les arguments nommés résolvent ce problème en rendant explicite l'objectif de chaque paramètre au point d'appel. Ils évitent également les bugs liés au réordonnancement des paramètres lorsque les signatures de fonction changent.

Pourquoi c'est important

Maintenabilité du code : Les arguments nommés documentent l'intention au point d'appel sans nécessiter une vérification constante des références. Lorsque vous voyez sendEmail(to: $email, retry: true, async: false, timeout: 30), vous comprenez exactement ce que chaque valeur contrôle. Cela élimine la confusion lors de la revue de code et accélère le débogage, car vous n'avez pas besoin de mapper mentalement les arguments positionnels aux noms de paramètres.

Implications en matière de sécurité : Les erreurs d'ordre des paramètres dans les fonctions critiques pour la sécurité peuvent créer des vulnérabilités. Échanger le $username et $password paramètres, ou le fait de passer accidentellement le mot de passe en clair là où le mot de passe haché devrait se trouver, échoue silencieusement avec les arguments positionnels. Les arguments nommés vous obligent à spécifier explicitement quelle valeur va où, prévenant ainsi ces erreurs dangereuses.

Sécurité du refactoring : L'ajout de paramètres optionnels à des fonctions existantes rompt tous les sites d'appel utilisant des arguments positionnels, à moins de les ajouter à la fin. Les arguments nommés permettent d'ajouter, de réordonner ou de modifier des paramètres sans casser le code existant, tant que les noms des paramètres restent cohérents. Cela rend les API plus stables et leur évolution moins risquée.

Exemples de code

❌ Non conforme :

function createUser($email, $password, $role, $verified, $sendEmail, $retryCount) {
    $hashedPassword = password_hash($password, PASSWORD_BCRYPT);

    $user = User::create([
        'email' => $email,
        'password' => $hashedPassword,
        'role' => $role,
        'verified' => $verified
    ]);

    if ($sendEmail) {
        sendWelcomeEmail($user->email, $retryCount);
    }

    return $user;
}

// Unclear what each parameter means
createUser('user@example.com', 'secret123', 'admin', true, false, 3);

Pourquoi c'est incorrect : Le site d'appel ne fournit aucun contexte pour ce qui est vrai, faux, et 3, nécessitant une référence constante à la signature de la fonction. L'échange de $role et $password ou $verified et $sendEmail échouerait silencieusement, créant potentiellement des problèmes de sécurité.

✅ Conforme :

function createUser(
    string $email,
    string $password,
    string $role = 'user',
    bool $verified = false,
    bool $sendEmail = true,
    int $retryCount = 3
) {
    $hashedPassword = password_hash($password, PASSWORD_BCRYPT);

    $user = User::create([
        'email' => $email,
        'password' => $hashedPassword,
        'role' => $role,
        'verified' => $verified
    ]);

    if ($sendEmail) {
        sendWelcomeEmail($user->email, $retryCount);
    }

    return $user;
}

// Self-documenting call site
createUser(
    email: 'user@example.com',
    password: 'secret123',
    role: 'admin',
    verified: true,
    sendEmail: false,
    retryCount: 3
);

Pourquoi c'est important : Le but de chaque paramètre est explicite au point d'appel, ce qui rend le code auto-documenté. Les erreurs d'ordre des paramètres sont impossibles puisque chaque argument est nommé explicitement, et l'ajout de nouveaux paramètres optionnels ne cassera pas le code existant.

Conclusion

Utilisez des arguments nommés pour les fonctions avec plus de 2-3 paramètres, des drapeaux booléens ou des types similaires apparaissant consécutivement. La légère verbosité au point d'appel est compensée par la clarté, la sécurité et la maintenabilité. Réservez les arguments positionnels pour les fonctions simples où l'ordre des paramètres est évident et peu susceptible de changer.