+12

Dicas de estilo de programação

criado por Rubens Takiguti Ribeiro em 22/03/2010 1:43am
Documentação do Código-fonte

A documentação do código-fonte é muito importante não apenas para outros programadores se inteirarem sobre o que determinado script faz, mas até mesmo para o próprio autor do arquivo se cituar frente a um sistema composto por centenas ou, até, milhares de arquivos.

A documentação de um arquivo começa pela descrição do que o arquivo faz. Pode guardar informações como o autor, versão, data, licença, lista de mudanças, etc. Esta documentação pode ser colocada em um formato especial e padronizado, como por exemplo aquele definido pelo PHPDoc (semelhante ao JavaDoc). Desta forma, é possível gerar a documentação de todo o código-fonte de maneira automatizada (http://www.phpdoc.org/). Note que isso não elimina a necessidade de uma documentação mais detalhada do sistema, que apresenta a interação entre os módulos, a visão geral sobre cada módulo, e a visão geral sobre o sistema, seus perfis de acesso, etc.

Além disso, as funções, classes, atributos e métodos também devem ser documentados a fim de facilitar o entendimento. Dar nomes longos a funções, métodos ou atributos pode torná-lo mais legível, mas também pode ser algo extremamente frustrante para alguns programadores. Porém, determinar um padrão é essencial. Você não precisa chamar todas as chaves primárias das tabelas do seu BD com o formato "codigo_do_...", mas se você determinar o padrão "cod_..." ou simplesmente "id", use-o sempre. O importante é que o padrão seja definido e esteja documentado em algum lugar. Desta forma, qualquer membro da equipe de desenvolvimento saberá que as PKs tem tal formato e não precisarão pensar ou ver em algum lugar.

A seguir, um exemplo de método documentado com o padrão PHPDoc:
/**
 * Metodo que filtra os elementos de um vetor de acordo com o tipo informado
 * @param int $tipo Tipo de elemento a ser filtrado (veja constantes TIPO_...)
 * @param array $vetor Vetor a ser filtrado
 * @return array Vetor com os elementos filtrados
 */
public function filtrar($tipo, $vetor) {
    ...
}

Para explicar pequenos trechos de código ou estratégias adotadas, é útil utilizar comentários de linha ou de bloco. Porém, comentários demais também pode ser prejudicial. O ideal é explicar apenas aquilo que não é percebido no código em menos de 1 minuto, por exemplo. Em geral, o código precisa ser estruturado em níveis de abstração cada vez maiores, de forma que se tornem extremamente legíveis e simples, já que a complexidade é "diluída" entre os níveis.

Comentários:

Mostrando 1 - 10 de 11 comentários
Cara... Muito bom! Aprendi, e muito, com este artigo!
10/05/2012 12:00pm (~6 anos atrás)

Parabéns pelo artigo! :-)

Por isso eu acho importante o uso de frameworks, pois eles seguem certos padrões de desenvolvimento e não vira bagunça.
31/03/2011 2:15am (~7 anos atrás)

Josué, a quantidade de memória usada pelo PHP em uma execução é limitada pela diretiva memory_limit, do php.ini. Você consegue alterar o valor dela em tempo de execução chamando a função ini_set:
ini_set('memory_limit', '128M');

Se não me engano, o padrão é 128M, que já é uma quantidade considerável. O conteúdo gerado por uma página normalmente tem de 50Kb a 300Kb. Em casos extremos, pode chegar a 1Mb, mas é muito abaixo de 128M.

Um detalhe que ajuda a usar menos memória é encapsular bem os métodos. Assim, as variáveis (não estáticas) criadas exclusivamente para os métodos são desalocadas assim que o método termina a execução. Ou, caso alguma variável gigante não precisa mais ser usada em determinado ponto do código, usa-se unset para desalocá-la.
18/01/2011 2:35pm (~7 anos atrás)

Josue Samuel disse:
Há tempos venho ensaiando criar um script com o layout html como o exemplo da página 2 do artigo em questão.

Depois, eu utilizaria uma variável única pra concatenar o conteúdo gerado por uma página em específico e, ao termino de todo o processamento, imprimí-la no local adequado conforme a abordagem do Carlos Eduardo Gomes Monteiro (segundo post de baixo pra cima).

Entretanto, ainda não me sinti confortável em somar essas duas abordagens em especial pelo fato de não ter tando controle da quantidade de dados armazenado na variável que daria o output do conteúdo. Esse desconforto de seve em eu não saber exatamente o tamanho/memória consumida que o PHP/servidor suportaria.

Alguém tem idéia qual o limite máximo de tamanho de uma variável e no que isso pode impactar para o servidor?
18/01/2011 12:20pm (~7 anos atrás)

Não conhecia o heredoc e nowdoc... bem interessante
21/11/2010 12:06pm (~7 anos atrás)

Cara, estou impressionado, cada dia que passa, descubro que conheço menos de PHP hehehe Parabéns !!!
30/09/2010 9:57am (~8 anos atrás)

Anderson disse:
Sou novo no site phpbrail, quero dar os parabéns pelo artigo, achei sensacional.
Abraço.

Anderson de Oliveira Morais.
28/09/2010 12:09pm (~8 anos atrás)

Filipe Mtro disse:
Acho interessante a forma de usar os arquivos .tpl com as variáveis, as vezes vejo coisa como %%TPL_RODAPE%% e Olá você tem %s créditos e %s de débitos.

Alguem pode me explicar o uso dessa tecnologia?
Eu realmente ainda não entendi.
15/06/2010 5:06am (~8 anos atrás)

Wake Up disse:
Muito bom!

Principalmente a parte sobre as notações "heredoc" e "nowdoc" (que eu desconhecia até então).

[]'s
Mario
08/06/2010 1:45pm (~8 anos atrás)

Ótimo artigo!!!
Duas coisas que gostaria de comentar.

Esta parte
$time = time();
foreach ($itens as $item) {
    if ($item->tamanho > $tamanho_minimo) {
        foreach ($item->elementos as $elemento) {
            if ($elemento->visivel) {
                echo '<p>';
                if ($data > $time) {
                    echo 'teste';
                }
                echo $elemento->nome;
                echo '</p>';
            }
        }
    }
}

Eu prefiro ao invés de imprimir, eu gosto sempre de atribuir a variaveis e fazer a impressão apenas no final.
Que inclusive, algo que você citou no começo de forma sutil mas não detalhada.
Eu sempre atribuo tudo à variaveis.
Deixando as impressões apenas para o final.
Pois assim, toda a execução do PHP seria feita, e apenas após concluir é que viria o HTML.
Isso ajuda muito em relação do uso de funções como header(), session_start() e etc...

Outro ponto importante que você comentou foi os parametros nas funções.
Isso realmente é um problema quando se cria muitos parametros.
Eu também faço como você as vezes, utilizando arrays para parametros opcionais.
Mas uma outra forma de faze-lo.
É em caso de métodos de uma classe, utilizar métodos GET e SET para determinar os parametros opcionais.
Ou seja, dentro da classe, já seta os atributos com valores padrões, e utilizando o SET apenas para o caso de setar um valor diferente do padrão.
Isto também dá mais clareza ao código, pois fica mais fácil de ser entendido, sendo que utilizando array, o programador vai ter que ler o código para entender como ele deve escrever o array com os valores opcionais...

Mas estes dois pontos é claro, é tudo uma questão de estilo né...
Só estou deixando o meu ponto de vista, quem sabe agrade alguem né...

Abraço a todos!!!
07/06/2010 12:07pm (~8 anos atrás)

Novo Comentário:

(Você pode usar tags como <b>, <i> ou <code>. URLs serão convertidas para links automaticamente.)