Regra
Utilização os argumentos argumentos para claridade
Argumentos nomeados argumentos tornam o código auto-documentado 
e evitar parâmetros ordem erros.
Use argumentos argumentos quando funções têm mais
do que 2-3 parâmetros ou booleanos sinalizadores.

Idiomas suportados: Python, PHP

Introdução

Funções com múltiplos parâmetros tornam-se pouco claras ao observar o local da chamada. Ler sendEmail('user@example.com', true, false, 30) exige consultar a assinatura da função para entender o que true, falso, e 30 significa. Argumentos nomeados resolvem isso tornando o propósito de cada parâmetro explícito no local da chamada. Eles também previnem bugs decorrentes da reordenação de parâmetros quando as assinaturas de função mudam.

Por que isso importa

Manutenibilidade do código: Argumentos nomeados documentam a intenção no local da chamada sem exigir verificação constante de referência. Quando você vê sendEmail(to: $email, retry: true, async: false, timeout: 30), você entende exatamente o que cada valor controla. Isso elimina a confusão durante a revisão de código e acelera a depuração, já que você não precisa mapear mentalmente argumentos posicionais para nomes de parâmetros.

Implicações de segurança: Erros na ordem dos parâmetros em funções críticas de segurança podem criar vulnerabilidades. Trocar os $username e $password parâmetros, ou passar acidentalmente a senha em texto simples onde a senha hash deveria estar, falha silenciosamente com argumentos posicionais. Argumentos nomeados forçam você a declarar explicitamente qual valor vai para onde, prevenindo esses erros perigosos.

Segurança na Refatoração: Adicionar parâmetros opcionais a funções existentes quebra todos os pontos de chamada com argumentos posicionais, a menos que você os anexe no final. Argumentos nomeados permitem adicionar, reordenar ou alterar parâmetros sem quebrar o código existente, desde que os nomes dos parâmetros permaneçam consistentes. Isso torna as APIs mais estáveis e a evolução menos arriscada.

Exemplos de código

❌ Não-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);

Por que está errado: O local da chamada não fornece contexto para o que é verdadeiro, falso, e 3 significam, exigindo referência constante à assinatura da função. Trocar $role e $password ou $verified e $sendEmail falharia silenciosamente, potencialmente criando problemas de segurança.

✅ Compatível:

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

Por que isso importa: O propósito de cada parâmetro é explícito no local da chamada, tornando o código autodocumentado. Erros na ordem dos parâmetros são impossíveis, pois você nomeia explicitamente cada argumento, e adicionar novos parâmetros opcionais não quebrará o código existente.

Conclusão

Use argumentos nomeados para funções com mais de 2-3 parâmetros, flags booleanas ou tipos semelhantes que apareçam consecutivamente. A ligeira verbosidade no local da chamada compensa em clareza, segurança e manutenibilidade. Reserve argumentos posicionais para funções simples onde a ordem dos parâmetros é óbvia e improvável de mudar.