Padrões de codificação PHP

Os padrões de codificação abaixo são muito importantes para a legibilidade do código. Procure seguir fielmente o que está descrito neste documento, para que o seu código fique padronizado e possa ser lido por outras pessoas que venham a dar manutenção em seu processo.

Idioma de codificação

• Usar sempre o idioma inglês na codificação de classes, métodos, atributos, constantes,etc. Para os comentários, já que são facultativos, usar preferencialmente o inglês.

Tags PHP

• Usar <?php ?> para delimitar código PHP, pois é a forma mais portável de incluir código PHP em diferentes sistemas operacionais e configurações.

Identação e comprimento de linha

• Usar tabulação equivalente a 3 espaços.

• É recomendado que as linhas tenham entre 75-85 caracteres.

Comentários

• Comentários (blocos) de documentação PHPDoc são obrigatórios.

• Comentários não referentes a documentação são recomendados.

• Comentários estilo multi-linha (/* */) e linha única () são recomendados, ao passo que estilos Perl/shell (#) devem ser evitados.

Incluindo código

• Usar require_once ao incluir incondicionalmente arquivos de classe.

• Usar include_once ao incluir condicionalmente arquivos de classe.

• require_once e include_once não são funções, portanto parênteses não devem envolver o nome do arquivo.

Convenções de nomenclatura

Classes

• Devem ter nomes descritivos. Evitar usar abreviações. Nomes de classes devem começar com uma letra maiúscula.

• Exemplos: Classe, MinhaClasse.

Métodos e funções

• Devem usar o padrão camel-case (Java).

• Exemplos: metodo, meuMetodo.

• Membros privados de classes são precedidos de um underscore.

Constantes

• Escritas em letras maiúsculas, com underscores separando palavras.

• Podem ser prefixadas com o nome da classe/pacote onde elas são usadas.

• As constantes true e false são exceções e devem ser escritas com letras minúsculas.

Variáveis globais

• Se o projeto precisar definir variáveis globais, seus nomes devem iniciar com um underscore seguido pelo nome do projeto e outro underscore. Por exemplo, o pacote PEAR usa uma variável global chamada $_PEAR_destructor_object_list.

Estruturas de controle

• Incluem as instruções if, for, while, switch, etc. Segue abaixo um exemplo:

    <?php

      if ( (condition1) || (condition2) )
      {
         action1;
      }
      elseif ( (condition3) && (condition4) )
      {
         action2;
      }
      else
      {
         defaultaction;
      }

    ?>

• Instruções de controle devem ter um espaço entre a palavra-chave e a abertura de parênteses, para distingui-los de chamadas de funções.

• É recomendado sempre usar chaves mesmo em situações onde elas são tecnicamente opcionais, pois aumentam a clareza da leitura e diminui a chance de erros lógicos serem introduzidos quando novas linhas forem adicionadas.

• Para instruções switch:

    <?php

    switch ( condition )
    {
        case 1:
            action1;
        break;

        case 2:
            action2;
        break;

        default:
            defaultaction;
    }
    ?>

Chamadas de função

• Devem ser feitas sem espaços entre o nome da função e os parênteses, e o primeiro parâmetro; espaços entre vírgulas e cada parâmetro, e sem espaço entre o último parâmetro e o parênteses e o ponto-e-vírgula. Segue um exemplo:

    <?php

    $var = foo($bar, $baz, $quux);

    ?>

• Como mostrado acima, deve haver um espaço entre a variável e o operador de atribuição e entre o operador e a chamada a função. Pode ser introduzidos mais espaços para aumentar a legibilidade.

    <?php

    $short         = foo($bar);
    $long_variable = foo($baz);

    ?>

Definição de funções

• Argumentos com valores padrão aparecem ao final da lista de argumentos. Exemplo:

    <?php
    function fooFunction($arg1, $arg2 = '')
    {
        if ( condition )
        {
            statement;
        }
        return $val;
    }
    ?>

Definição de classes

• A chave de abertura fica na linha inferior ao do nome da classe e a de fechamento fica na linha seguinte da última linha de código.

    <?php

    class Classe
    {
      /* código PHP */ 
    }

    ?>