Introduction

Você já se deparou com um verificador de estilo reclamando que uma linha é muito longa, mesmo que pareça razoável? Este guia esclarece as diretrizes de comprimento de linha do PSR-2, abordando especificamente a distinção entre limites rígidos e flexíveis. Você aprenderá o que esses limites são, como eles afetam a formatação automática de código e entenderá por que seu código pode ser sinalizado, apesar de parecer visualmente aceitável. Desmistificaremos as nuances das recomendações do PSR-2 para um código mais limpo e legível.

Regras de Comprimento de Linha PSR-2

PSR-2 define diretrizes de comprimento de linha para código PHP, mas as regras podem ser confusas. O padrão estabelece dois limites de comprimento de linha: um máximo preferencial de 80 caracteres e um limite "suave" de 120 caracteres. Linhas de até 80 caracteres são consideradas ideais e sempre aceitáveis.

O "limite suave" de 120 caracteres significa que ferramentas automatizadas, como linters e IDEs, devem emitir um aviso se uma linha exceder esse comprimento. No entanto, essas ferramentas não devem tratar o excesso de 120 caracteres como um erro que impeça a execução do código. A intenção é incentivar a legibilidade, permitindo exceções ocasionais onde dividir uma linha seria prejudicial.

Essencialmente, priorize manter as linhas com menos de 80 caracteres sempre que possível. Se uma linha exceder 80, mas permanecer abaixo de 120, geralmente é aceitável, mas esteja atento à legibilidade. Linhas com mais de 120 caracteres requerem atenção e um aviso de ferramentas automatizadas.

<?php

/**
 * Function to calculate the sum of two numbers.
 *
 * @param int $a First number.
 * @param int $b Second number.
 * @return int Sum of the two numbers.
 */
function addNumbers(int $a, int $b): int {
    return $a + $b;
}

// Example usage
$result = addNumbers(5, 3);
echo "The sum is: " . $result;

?>

Interpretando Limites Flexíveis vs. Rígidos

PSR-2 define duas diretrizes de comprimento de linha para código PHP, diferenciadas pela sua severidade para verificadores de estilo automatizados. O "limite suave" de 120 caracteres atua como uma sugestão. Os verificadores de estilo são instruídos a emitir avisos quando as linhas excedem este limite, mas não devem reportá-las como erros que interrompem o processo.

O "limite rígido" não existe em PSR-2. As linhas idealmente devem permanecer abaixo de 80 caracteres, particularmente ao dividir linhas longas em várias linhas subsequentes. Isso promove a legibilidade e a manutenção.

Essencialmente, procure manter as linhas com menos de 80 caracteres, mas linhas ocasionais de até 120 são permitidas, gerando apenas um aviso de ferramentas automatizadas. O ponto principal é que as diretivas "DEVE" e "PRECISA" se aplicam a verificadores de estilo automatizados, e não às ações de codificação diretas do programador.

<?php
/**
 * Function to interpret soft vs hard limits.
 *
 * @param int $softLimit Soft limit value.
 * @param int $hardLimit Hard limit value.
 * @return string Interpretation of the limits.
 */
function interpretLimits($softLimit, $hardLimit) {
    // Check if inputs are valid integers
    if (!is_int($softLimit) || !is_int($hardLimit)) {
        return "Error: Both soft and hard limits must be integers.";
    }

    // Compare soft and hard limits
    if ($softLimit > $hardLimit) {
        return "Soft limit exceeds hard limit. Please adjust.";
    } elseif ($softLimit == $hardLimit) {
        return "Soft and hard limits are equal.";
    } else {
        return "Soft limit is within the acceptable range of the hard limit.";
    }
}

// Example usage
$soft = 10;
$hard = 20;

$result = interpretLimits($soft, $hard);
echo $result; // Output: Soft limit is within the acceptable range of the hard limit.
?>

Implicações Práticas para Desenvolvedores

As diretrizes de estilo de codificação PSR-2 estabelecem recomendações de comprimento de linha para código PHP, mas a distinção entre limites "soft" e "hard" pode ser confusa. O padrão dita um limite "soft" de 120 caracteres e um máximo preferencial de 80 caracteres. Esses limites se referem principalmente a verificadores de estilo automatizados, não ao desenvolvedor diretamente.

O limite "soft" de 120 caracteres significa que excedê-lo não acionará um erro de ferramentas automatizadas. Em vez disso, essas ferramentas são obrigadas a emitir um aviso, indicando um problema potencial de legibilidade. Linhas que excedem 80 caracteres devem, idealmente, ser divididas em várias linhas para manter a clareza do código.

Em essência, os desenvolvedores devem se esforçar para manter as linhas com menos de 80 caracteres sempre que possível. Linhas ligeiramente mais longas são aceitáveis, mas ferramentas automatizadas as sinalizarão como um aviso, incentivando a consideração de refatoração para melhor legibilidade.

<?php
// Function to fetch user data from a database
function getUserData($userId) {
    // Database connection parameters
    $host = 'localhost';
    $dbname = 'example_db';
    $username = 'root';
    $password = '';

    try {
        // Create a new PDO instance
        $pdo = new PDO("mysql:host=$host;dbname=$dbname", $username, $password);
        $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

        // Prepare the SQL query to fetch user data
        $sql = "SELECT * FROM users WHERE id = :userId";
        $stmt = $pdo->prepare($sql);

        // Bind the parameter and execute the query
        $stmt->bindParam(':userId', $userId);
        $stmt->execute();

        // Fetch the result as an associative array
        $userData = $stmt->fetch(PDO::FETCH_ASSOC);

        if ($userData) {
            return $userData;
        } else {
            throw new Exception("User not found");
        }
    } catch (PDOException $e) {
        // Handle database connection or query errors
        echo "Database error: " . $e->getMessage();
        return null;
    }
}

// Example usage
$userId = 1;
$userData = getUserData($userId);

if ($userData) {
    echo "User ID: " . $userData['id'] . "<br>";
    echo "Username: " . $userData['username'] . "<br>";
} else {
    echo "Failed to retrieve user data.";
}
?>

Conclusion

Em última análise, as diretrizes de comprimento de linha do PSR-2, particularmente o limite “suave” de 80 caracteres, priorizam a legibilidade e a colaboração. Embora não sejam aplicadas estritamente, aderir a este padrão promove um código mais limpo e facilita os processos de revisão. Compreender a distinção entre limites suaves e rígidos capacita os desenvolvedores a tomar decisões informadas sobre a formatação do código, equilibrando as necessidades do projeto com as convenções estabelecidas.