Boas Práticas de Codificação

Esta página apresenta a convenção recomendada no desenvolvimento dos artefatos de software para o Pandora visando padronizar e facilitar o entendimento da sua estrutura por outras pessoas.

A convenção é importante por uma série de motivos:

  • 80% do custo de tempo de vida de um artefato de software está na manutenção;
  • Dificilmente o autor do software será responsável pela sua manutenção durante todo o tempo de vida;
  • Convenções facilitam a leitura do código, permitindo a outros programadores e aos gestores entender novos códigos de forma rápida e completa; e
  • Se o projeto se transformar em um produto comercial, é necessário garantir que seu código esteja limpo e conciso.
  • Outro importante benefício é que, a partir do momento em que se convenciona boas práticas para codificação, a adoção de uma IDE unificada torna-se desnecessária, podendo o programador adotar aquela em que se sinta mais confortável.
  • Assim, seguindo a convenção de código do Titan Framework e a convenção adotada na Arquitetura de Desenvolvimento de Software PHP da Embrapa, a convenção de código utilizada para o desenvolvimento do Pandora normatiza que:
  • Sempre se utilize nomes de variáveis, funções, classes e demais entidades em inglês;
  • Sempre se utilize Camel Case para nomear variáveis locais e funções (p.e., $myVar ou myFunction ());
  • Atributos privados devem ser precedidos com um underscore (p.e., $_myVar);
  • Sempre se utilize Pascal Case para nomes de classes (p.e., MyClass);
  • Sempre se utilize Upper Case precedido de um underscore para variáveis globais (p.e., $_MY_VAR);
  • Sempre se utilize Upper Case entre undescores (_MY_CONST_) para constantes;
  • Sempre se utilize Orientação a Objetos ;
  • Se procure manter funções pertinentes dentro das classes (mesmo que sejam métodos estáticos);
  • Sempre se quebre linha após ponto-e-vírgula, antes de um operador ou antes de abrir chaves (delimitador de escopo);
  • Sempre se utilize tabulação para identação, e jamais espaços (é importante configurar na IDE de desenvolvimento, pois muitas colocam, por padrão, espaço);
  • Sempre se feche parênteses e chaves na mesma coluna ou na mesma linha em que foram abertos;
  • Utilize-se linhas em branco: entre funções e métodos, entre classes e entre expressões com variáveis distintas;
  • Em todos os arquivos deve-se utilizar o padrão de cabeçalhos e comentários especificado pelo PHPDoc;
  • Sempre que aplicável, se utilize Design Patterns; e
  • Jamais se utilize de deprecated features.

Em relação ao Banco de Dados, convenciona-se que:

  • Os nomes de todas as entidades do banco de dados sejam sempre em inglês, em caixa baixa (lower case) e com as palavras separadas por underscore (p.e., my_table); e
  • Os nomes das tabelas sejam sempre no singular.