Padrões de Codificação

From COREPHP

Padrões de Codificação são importantes a fim de evitar que o código torne-se uma multiplicidade de estilos dificultando a leitura e compreensão do código por desperdício de foco na tentativa de compreender o que a linha quer dizer sem realmente analisar a sintaxe da mesma.

Para tanto os seguintes estilos serão adotados, tanto nos códigos em Javascript quanto nos códigos em PHP.

Charset dos arquivos

Todos os arquivos serão salvos no formato UTF-8. Isso ocorrerá a fim de seguir uma tendência mundial de interoperabilidade entre sistemas criados em idiomas diferentes, evitando os problemas que eram gerados com acentuações e caracteres especiais.

Quebras de linha

Utilizaremos o padrão unix de quebra de linha, ou seja, \n, ao invés do padrão windows \r\n.

Identação e comprimento de linha

Utilizaremos sempre a identação no estilo BSD/Allman também conhecida como estilo ANSI.

Para identação, utilizar \t (tabs). No seu editor, configure para que a tab tenha o tamanho de 4 espaços (atenção, é para inserir tabs e mostrar na tela como se fossem 4 espaços, e não inserir 4 espaços quando pressionar-se o tab).

O Comprimento de linha deve limitar-se a 120 caracteres, sendo o ideal manter-se entre 75-85 caracteres (para facilidade de leitura em terminais texto, quando necessário).

Convenção de Nomes

Classes - Iniciam-se sempre em maiúscula, e se compostas por mais de uma palavra, cada palavra também deverá ser iniciada por maiúscula. Ex: PessoaFisica, PessoaJuridica, Aluno, AlunoTurma, etc.

Métodos e Funções - Utilizar o padrão "camel caps", isto é, a primeira em minúscula e o restante composto com maiúscula na primera. Ex: pegaAtributo, defineAtributo, etc.

Variáveis e Atributos - Sempre em minúsculas

Vide Padrões de Nomenclatura para maiores detalhes

Marcadores de início

Devem aparecer na primeira coluna de texto, e o conteúdo deve estar identado em relação a eles. Devem ser sempre encerrados! Mesmo que a linguagem PHP permita que não se feche o código com ?>, o mesmo deve ser sempre colocado ao final do arquivo.

Ex:

   <script>
       conteúdo
   </script>

ou

   <?
       conteúdo
   ?>

Obs: arquivos Javascript inclusos não podem ter <script></script> delimitando-os, pois isto causa erro. Nestes casos, é permitido que se crie o arquivo sem os marcadores, pois é uma limitação técnica da linguagem.

Estruturas de Controle

As estruturas de controle são if, switch, while, etc.

Devem conter um espaço entre o comando e a abertura dos parêntesis, para facilidade de leitura.

Utilizar sempre as chaves, mesmo quando tecnicamente estas forem uma opção.

Não criar comandos de uma linha só. Se você tiver um if de uma linha só, então quebre-o e chavei-o conforme os padrões aqui estabelecidos.

O chaveamento segue o estilo BSD/Allman. Ou seja, as chaves {} seguem logo abaixo do comando, com a mesma identação.

As chaves de abertura e encerramento não podem estar na mesma linha.

O conteúdo dentro da chave deve estar identado também.

Ex:

   if (algo)
   {
       faça algo;
   }

No caso de switchs, o case deve estar identado para dentro das chaves, e os itens dentro do switch também devem estar identados. breaks também ficam identados.

Ex:

   switch ($algo)
   {
       case 1:
           faça algo;
           break;
       case 2:
           faça outra coisa;
           break;
       default:
           faça algo;
           break;
   }

Definição de Funções e métodos

Também devem seguir o estilo BSD/Allman, conforme acima.

Ex:

   function ()
   {
       conteúdo da função;
   }

Chamada de Funções

As funções devem ser chamadas sem espaço entre o nome da função e os parêntesis.

Ex:

   $retorno = funcao($param1, $param2);

Comentários

Os comentários devem ser utilizados como inserir explicações sobre o código, e não para comentar código. Caso algum código seja comentado durante o desenvolvimento, para seu commit no CVS e sua publicação em produção o mesmo deverá ser removido.

Ex:

   //a linha abaixo verifica a veracidade de uma situacao
   if ($veracidade)
   {
       facaalgo();
   }

O Exemplo abaixo é impróprio

   //a linha abaixo verifica a veracidade de uma situacao
   if ($veracidade)
   {
       //antigofacaalgo();
       facaalgo();
   }

Documentação

Para o correto uso de comentários, vide Padrões de Documentação - PHPDoc e Padrões de Documentação - JsDoc.

Inclusão de Código

Não utilizar include_once ou require_once em nenhum momento.

Todas as inclusões devem ser feitas no arquivo sysincludes.php. Isto ajudará a centralizar todos os includes necessários, facilitando a localização de um erro.

Utilize preferencialmente require.

Para inclusões de código Javascript, utilizar um único include também, a fim de evitar que um código seja carregado antes de outro do qual ele dependa, ou mensagens de erro poderão aparecer no console do navegador, sem necessariamente representarem um erro.