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:

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.

ini_set('memory_limit', '128M');

$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>';
            }
        }
    }
}