Subscribe:

About

sábado, 1 de setembro de 2012

Práticas de programação

Quase toda atividade possui um conjunto de boas práticas para assegurar um mínimo de qualidade ao trabalho, garantindo conformidade, menor chance de erros e outros benefícios específicos dependendo do contexto. E no desenvolvimento de software não poderia ser diferente. Trago aqui algumas informações acerca de algumas boas práticas e por que adotá-las.


Documentação de código


É comum achar que documentação e código são entidades completamente diferentes dentro do ciclo de desenvolvimento e devem ficar separadas, com pessoas distintas responsáveis por cada um. Hoje, essa ideia é geralmente refutada em favor da documentação acoplada ao próprio código, produzida a partir de comentários e declarações.

A documentação de código permite esclarecer questões de implementação que de outra forma não ficariam claras. Por que uma determinada decisão foi tomada, por que as demais alternativas foram descartadas e que soluções foram empregadas podem ser aspectos cruciais quando se precisa realizar alguma manutenção, reusar o código ou adaptá-lo de alguma forma.

De forma geral, os comentários devem explicar por que, e não como. Idealmente, o código deve ter um grau de "auto-documentação" satisfatório, de modo que não seja necessário explicar, linha por linha, o que está acontecendo. Como atingir essa clareza será descrito na seção "Recomendações gerais".

A linguagem Java fornece a ferramenta Javadoc para gerar a documentação do código de forma automática (confira um guia completo aqui), tendo suporte de IDEs como o Eclipse. Em Eclipse, para gerar um template automático, basta inserir /*** seguido por "Enter". Por exemplo, considere o método:

public int soma(int a, int b) {
   return a + b;
}


Se digitarmos /*** e depois teclarmos "Enter" logo acima do método, obteremos a seguinte estrutura:

/***
*
* @param a
* @param b
* @return
*/


public int soma(int a, int b) {
   return a + b;
}

Agora podemos facilmente adicionar a descrição do método, dos parâmetros, e do retorno. Feito isso, clique com o botão direito no projeto e selecione "Export...". Procure pela opção de exportar Javadoc e, se precisar, insira como comando o local onde se encontra o arquivo javadoc.exe. Provavelmente está em Java\jdk\bin. Em seguida, será gerada uma pasta chamada "doc" no projeto e nela se encontrará um arquivo "index.html" parecido com este:

Clique para ampliar.

Princípio KISS


O princípio KISS é bem direto: "Keep It Simple, Stupid" ou "Keep It Simple Stupid". Mantenha o código o mais simples possível, de modo que cada módulo seja capaz de resolver apenas um pequeno problema bem definido. Parece banal, mas na prática é muito mais fácil deixar um código complexo do que simples, com classes sobrecarregadas de funcionalidades, métodos que resolvem mil e um problemas, e várias gambiarras.

Se for definido que cada módulo só fica responsável por um problema, o código torna-se muito mais fácil de se testar, ser modificado e passar por manutenções, além de possibilitar que um número maior de problemas seja resolvido em menos tempo.

Há vários modos de aplicar o princípio KISS, sendo a maioria delas questão de bom senso:

  • Quebrar uma tarefa complexa em vários problemas menores, cada qual podendo ser resolvido com poucos módulos.
  • Escrever pequenos módulos, sejam eles classes, interfaces ou métodos. Para métodos, o ideal é ter até cerca de 40 linhas, mas não é uma métrica exata.
  • Evitar classes cheias de métodos. Quando isso acontece, geralmente é sinal de que não está havendo uma separação de conceitos adequada.
  • Ter uma solução bem delineada antes de começar a codificar qualquer coisa, a não ser que seja um problema simples.

Há algum método mais concreto, que permita uma análise quantitativa do código? Uma possibilidade é utilizar o conceito de complexidade ciclomática, uma métrica de código que se baseia nos possíveis caminhos do módulo. O ideal é que a complexidade ciclomática não ultrapasse 10, configurando uma função simples. Essa e outras formas de métrica estão disponíveis no Eclipse Metrics Plugin, que pode ser obtido nesta página.

Hard coding


Hard coding é uma prática adversa na qual o desenvolvedor coloca dados (por exemplo, o nome do banco de dados) no próprio código. Isso é justificado em ocasiões como quando não há, pelo menos no momento, meios que permitam a alteração dos dados a qualquer momento. Também pode ser utilizado para testes rápidos. Entretanto, é uma prática que deve ser inibida sempre que possível.

Ao fixar dados na própria aplicação, a portabilidade do código é severamente prejudicada ou mesmo anulada devido ao fato de alguns valores fixos só funcionarem localmente (como o nome do usuário do banco de dados) e, para ajustá-los, deve-se recompilar tudo. Pode ficar ainda pior: imagine que um valor é usado ao longo de vários trechos do código, mas não é armazenado por nenhuma variável. Isso implica em correções manuais cansativas e vulneráveis a erros.

A solução é investir na configurabilidade desde cedo, deixando tudo em meios de armazenamento externo. Mas se houver muita insistência em hard coding, convém ao menos guardar os valores em uma constante global dentro do módulo, o que já facilita a configuração e permite que ela receba informações de um arquivo no futuro. Adicionalmente, quaisquer cálculos e manipulações devem ser explicitamente declarados.

Recomendações gerais


Convenções


Se um conjunto ao menos básico de padrões não for estabelecido, o ambiente de desenvolvimento pode ficar caótico bem rápido: desenvolvedores têm dificuldade em utilizar o código um do outro, apenas os próprios autores dos módulos podem fazer manutenção neles e a integração do sistema exige esforços colossais. São coisas simples como "variáveis representando botões devem ter o sufixo -btn" ou "o código deve ser reformatado pela IDE", mas que fazem a diferença.

Nomes significativos


É clichê, mas sempre deve ser frisado. Nomes significativos são essenciais para se ter um código legível, auto-documentado. Para tal, deve-se evitar nomes extremamente abreviados a não ser em variáveis de escopo local, e absolutamente banir nomes sem relevância alguma que só foram postos por ser necessário fazê-lo (uma variável de nome "abc" que armazena um número de telefone, por exemplo).

Claro que há discordâncias quanto ao que exatamente constitui um código legível, mas, por via de regra, o bom senso deve prevalecer. Nomes como "r" e "rf" são tão ruins quanto "ruaDoFulanoDeTalVizinhoDoSicranoDeTal".

Formatação de código


Uso de indentação apropriada, quebra de linhas quando uma instrução for muito grande, linhas em branco para formar blocos lógicos com instruções relacionadas etc. são todas ações bastante simples, mas que podem fazer toda a diferença. Várias IDEs inclusive fazem boa parte da formatação automaticamente, então realmente não há motivos para deixar isso de lado.

Comentários


Além da documentação efetiva do código, comentários adicionais podem ser utilizados ao longo de um módulo para explicar alguma lógica que não seja evidente. É evidente, contudo, que comentários a cada três linhas ou menos de código claramente indicam algo de errado.

Tratamento de exceções


Pode ser tentador passar por cima das possíveis falhas ocorridas em um módulo, simplesmente imprimindo qualquer exceção que surja durante o caminho na saída padrão, mas é claro que erros podem e muito provavelmente vão acontecer. O código pode até ser "perfeito", mas o usuário sempre dá um jeitinho de quebrar tudo. Nessas ocasiões, quanto mais refinados forem os detalhes sobre o erro e quanto mais eficientemente essas informações forem exibidas, mais rápido fica para corrigir um bug no código.

Também é importante encapsular as informações de modo que o usuário receba apenas o que lhe interessa saber. Em mensagens de erro padrão, é comum ver uma descrição geral do problema, no que isso implica ao usuário e possíveis diagnósticos, tudo acompanhado por uma opção de "mostrar detalhes". É nesses detalhes que devem ser inclusos os detalhes técnicos que interessam aos desenvolvedores.

Fontes


How to Write Doc Comments for the Javadoc Tool
O princípio KISS e a Complexidade Ciclomática
Medindo a complexidade ciclomática em aplicativos Java
Self Documenting Code
The Kiss Principle

0 comentários:

Postar um comentário