Boas práticas em programação [Parte 01 de 02]

Um dos erros mais comuns em programação é escrever o código-fonte somente para si mesmo.

No momento em que o programador estiver escrevendo o programa, provavelmente ele não perceberá que a adoção de texto pouco legível e enigmático, por mais inteligente e astuto que possa inicialmente parecer, terminará prejudicando a ele mesmo, ainda que o código não seja destinado a ser usado ou lido por outras pessoas.

Outra prática ruim é a pressa no momento da escrita. Supõe-se ganhar tempo ao usar nomes curtos e de pouca significação, quando na verdade o tempo gasto para escolher nomes significativos poupará muito mais tempo posteriormente.

Isso porque a maioria esmagadora do tempo gasto em programação se faz exatamente com leitura de código-fonte. Pare para pensar a quantidade de tempo que você gasta rolando o texto para cima e para baixo, consultando classes e métodos e lendo comentários em comparação ao tempo que você gasta exclusivamente escrevendo. A verdade é inescapável: o programador lê constantemente código já escrito como parte do esforço para escrever código novo. Estima-se que a proporção de leitura e escrita durante a programação seja de 10:1.

Por isso, fazer com que o código-fonte seja fácil de ler na verdade o torna, ao mesmo tempo, fácil de ser escrito. Escrever código bem organizado, limpo, com o uso de nomes significativos para funções, variáveis e classes não é apenas recomendação de estilo, mas sim boa prática de qualquer programador com pretensões sérias ou profissionais.

Com base nessas premissas, o programador e autor Robert C. Martin escreveu o livro "Clean Code - A Handbook of Agile Software Craftsmanship", cuja leitura é altamente recomendada para qualquer programador, não importa a linguagem que se pretenda trabalhar. Os exemplos do livro estão em Java, mas aplicam-se a toda e qualquer linguagem orientada por objetos.

A seguir, tentei resumir algumas das principais dicas que pude extrair do livro, por vezes acrescentando alguns exemplos e comentários meus. Em postagens futuras acrescentarei mais dicas e exemplos.

Nomes significativos

Use nomes que revelam intenção

Escolher nomes bons toma tempo, mas economiza mais tempo do que toma. O nome (e não comentários) de uma variável, função ou classe deve responder todas as grandes questões sobre sua intenção.

Por exemplo, em vez de usar:

int d; // elapsed time in days

Use:

int elapsedTimeInDays;

Não há nenhum problema com nomes grandes, desde que sejam auto explicativos. As IDEs de hoje em dia (Eclipse, Netbeans, Aptana etc.) e seus recursos de auto-completar tornam a utilização de nomes grandes e explicativos totalmente viável.

Faça distinções significativas

De que adianta criar variáveis cuja significação não pode ser diferenciada uma da outra? Usar productData e productInfo em uma mesma classe ou em um mesmo contexto com certeza será motivo de confusão tanto para o autor do código como, pior ainda, para quem tiver que lidar com ele.

Use nomes pronunciáveis

Humanos são bons com palavras. Evite nomes impronunciáveis como genymdhms (generation date, year, month, day, hour, minute and second).  Muito mais adequado seria generationTimestamp. Este é pronunciável e aquele não.

Inglês, por favor!

Desnecessário dizer que é de todo recomendável, e às vezes até mesmo essencial, especialmente se você estiver trabalhando em código aberto ou opensource, que todos os nomes, expressões e comentários sejam escritos em inglês. Sim, primeiro porque a sintaxe da própria linguagem de programação já está em inglês e será muito confuso para qualquer pessoa ler código que está metade em inglês e metade na língua do autor do código. Pior ainda é misturar as duas línguas dentro de uma mesma função ou classe. Segundo porque, goste ou não, inglês é linguagem universal para programação (e para computadores em geral), de modo que a única forma de garantir que seu código será compreendido pelo resto de mundo será escrevê-lo em inglês.

Evite mapeamento mental

Às vezes vemos variáveis nomeadas com uma letra só. Sem dúvida são perfeitamente aceitáveis em um loop (i é a mais comum), mas desde que o loop seja pequeno e não haja conflitos. Em outros contextos, as variáveis de uma só letra certamente serão problemáticas, pois o leitor terá que fazer mapeamento mental daquela letra para o seu real significado. Com o passar do tempo, nem o próprio autor do código lembrará qual o verdadeiro conceito daquela variável de uma letra só.

Eis exemplo de função em JavaScript que é excelente em seu desiderato, porém praticamente impossível de ser examinada ou alterada sem muito tempo gasto com observação e teste. A função converte números para o formato dinheiro (string). Recebe como parâmetros os caracteres para milhar (t, de thousand) e decimal (d, de decimal) e a quantidade de casas decimais (c, de cases):

Number.prototype.toMoney = function(t, d, c) {
    var n = this,
    c = isNaN(c = Math.abs(c)) ? 2 : c,
    d = (d === undefined) ? "." : d,
    t = (t === undefined) ? "," : t,
    s = n < 0 ? "-" : "",
    i = parseInt(n = Math.abs(+n || 0).toFixed(c)) + "",
    j = (j = i.length) > 3 ? j % 3 : 0;
    return
        s + (j ? i.substr(0, j) + t : "") +
        i.substr(j).replace(/(\d{3})(?=\d)/g, "$1" + t) +
        (c ? d + Math.abs(n - i).toFixed(c).slice(2) : "");
};

Como se vê, qualquer alteração será extremamente penosa, especialmente porque foram usadas expressões regulares (regular expressions). Tivesse o autor dessa função usado nomes significativos para as variáveis e evitado mapeamentos mentais, a função seria muito mais proveitosa e fácil de ser atualizada e compreendida em sua implementação.

A diferença entre o programador esperto e o programador profissional é que o último entende que clareza é a rainha. Profissionais escrevem códigos que os outros conseguem ler e entender sem maiores esforços.

Nomes de Classes

Classes e Objetos devem ter nomes com substantivos como por exemplo Customer, WikiPage e Account. Se for usar um verbo, associe-o a um substantivo, como por exemplo AddressParser. Evite usar somente verbos, como por exemplo Manager ou Processor, principalmente porque verbos devem ser usados para métodos ou funções.

Nomes de Métodos

Métodos (ou funções) devem ser nomeadas com verbos, como por exemplo postPayment, deletePage ou save. Métodos que acessam, mudam ou predicam devem ser nomeados de acordo com o valor deles e prefixados com os verbos get, set ou is, como por exemplo getName, isPosted ou setColor.

Escolha uma palavra por conceito (coerência)

Escolha uma palavra para cada conceito abstrato e permaneça com ela até o fim. Não mude a palavra no meio do caminho. Por exemplo, é confuso usar palavras diferentes, porém de significado semelhante, para métodos equivalentes de classes diferentes, como por exemplo fetch, retrieve e get. Como você lembrará qual método pertence a qual classe?

Da mesma forma, é confuso ter palavras como controller, manager e driver na mesma base de código. Qual a diferença essencial, em termos de conceito, entre essas palavras? A diferença somente será descoberta se for feita a busca no código, o que tomará muito tempo de rolamento e navegação no texto.

Adicione contexto significativo

Muitas vezes você terá que colocar nomes dentro de contextos. Para tanto, deverá inseri-los em classes bem nomeadas, funções ou namespaces. Imagine as variáveis firstName, lastName, street, city, state etc. Quando juntas, fica muito claro que se referem a uma lista de endereços. Mas se você se deparar com state apenas, não concluirá automaticamente que se refere a um endereço postal. Nesse caso, a melhor opção é criar uma classe chamada Address e encapsular essas variáveis nessa classe, pois assim passarão a ser referenciadas por Address.state, Address.firstName e assim por diante, adicionando-se, dessa forma, contexto significativo às variáveis.

Funções

Pequenas!

A primeira e mais importe regra é que funções devem ser pequenas. A segunda regra é que devem ser menores ainda. Funções pequenas são fáceis de entender e facilitam o cumprimento do princípio que será abaixo descrito ("faça apenas uma coisa").

O tamanho pequeno da função implica blocos if, else e loops também pequenos. Na verdade, quanto mais perto de uma linha apenas forem os blocos, melhor será. Se preciso, o ideal é separar o código que viria dentro do bloco em outra função, preferencialmente como um nome bem descritivo para essa função, de forma a auto-documentar o código sem adicionar qualquer comentário, usando apenas o nome da função.

Faça uma coisa (apenas)

A regra de ouro é: "Funções devem fazer uma coisa. Devem fazê-la bem. Devem fazer somente essa coisa." O problema dessa regra é identificar o que seria "fazer apenas uma coisa". Em geral, essa regra deve ser entendida como a possibilidade de descer apenas um nível de abstração em relação ao verbo contido no nome da função (afinal, funções são escritas exatamente para decompor conceitos maiores em sequência de passos no próximo nível de abstração).

Para simplificar, o melhor jeito de saber se a função está fazendo "mais do que uma coisa" é verificar se é possível extrair outra função de dentro dela, porém com um nome que não seja mera repetição da implementação da função. Se isso for possível, então a função estará violando a regra "faça uma coisa (apenas)".

Isso leva ao princípio seguinte.

Um nível de abstração por função

Para se certificar que a função está fazendo "uma coisa (apenas)", deve ser verificado se as expressões contidas na função estão no mesmo nível de abstração. Se a função misturar conceitos de nível alto, intermediário e baixo de abstração, haverá confusão e o princípio estará sendo violado. Os leitores não conseguirão dizer se uma expressão em particular é um conceito essencial ou apenas um detalhe.

Leitura de código de cima para baixo: A regra de descer

O código deve poder ser lido como uma narrativa de cima para baixo. Isso significa que toda função deve ser seguida pela função do próximo nível de abstração, de forma que o código possa ser lido um nível de abstração por vez, de cima para baixo. Ajuda se pensarmos em termos de pequenas frases iniciadas por TO:

TO create a user, we generate an id number.
   TO generate an id number, we run the ramdom number generator.
      TO run the random number generator,
          we call a low level function.

No exemplo, cada frase iniciada por TO representa uma função diferente. É como se existisse um 'to' imaginário antes de cada nome de função, para nos ajudar a implementar o próximo nível de abstração:

public User (TO) createUser() {...}

Use nomes descritivos

Você sabe que está trabalhando com código de qualidade quando cada rotina faz exatamente aquilo que você espera. Quanto menor e mais focada a função, mais fácil será a escolha de um nome descritivo o suficiente. Não tenha medo de escolher nomes grandes. Nome grande e bem descritivo é melhor do que nome pequeno e enigmático.

Argumentos de funções

O número ideal de argumentos para uma função é zero. Depois um, seguido por dois. Três argumentos devem ser evitados sempre que possível. Mais do que três argumentos não são recomendados e precisam de justificativa realmente muito importante para serem usados.

Além disso, argumentos de saída devem ser evitados. Quando a função é lida, a tendência é interpretá-la como informação entrando na função por meio dos argumentos e saindo por meio do valor de retorno (return value). Em geral, não se espera que informação saia da função por meio dos argumentos.

Há duas boas razões para usar argumento único em uma função. Você pode estar fazendo uma pergunta sobe o argumento, como em boolean fileExists('myfile.txt'). Ou você pode estar operando sobre esse argumento, transformando-o em outra coisa e devolvendo o argumento alterado. Por exemplo: User getUserById(345).

É boa prática fazer da função e argumento, sempre que possível, um par verbo/substantivo, como por exemplo writeField(name).

Argumentos do tipo true ou false devem ser evitados, pois claramente indicam que a função vai fazer mais de uma coisa. Se o argumento for verdadeiro, terá um destino, se for falso, terá outro. O melhor seria criar uma função para cada caminho possível. Por exemplo, em vez de render(true), que por si só não revela nenhuma informação sobre o que seria a natureza do argumento, melhor seria criar duas funções separadas, como renderActiveFields() e renderInactiveFields(), em vez de deixar que o argumento leve a um resultado ou outro.

Use argumento duplo, quando inevitável, somente se entre os parâmetros houver estreita relação, como por exemplo range(1, 10). Fica evidente que você quer o intervalo entre 1 e 10. Seria estranho imaginar a função como range(1). Que intervalo isso representaria? Em casos como esse, é perfeitamente válido usar os dois argumentos. Mas por exemplo assertEquals(expected, actual) obriga o leitor a consultar a declaração da função, sob pena de confundir a ordem dos argumentos. Se for inevitável o uso de dois argumentos, o melhor é denunciar a ordem deles no nome da função, como por exemplo assertExpectedEqualsActual(expected, actual).

Quando uma função parecer precisar de mais de dois ou três argumentos, provavelmente alguns desses argumentos devem ser embrulhados em classes próprias, de forma que você passará objetos como argumentos. Reduzir o número de argumentos dessa forma pode parecer um atalho, mas não é. Quando variáveis são passadas em grupos, provavelmente elas já fazem mesmo parte de um conceito único, de forma que merecem fazer parte de uma classe única (só para elas).

Não use argumentos de saída

Argumentos são naturalmente intepretados como "entrada" de uma função. Na maioria das vezes, quando o argumento for "saída", você provavelmente terá que consultar a declaração da função para entender o que está se passando com ela.

Imagine o exemplo:

appendFooter(s);

Essa função acrescenta 's' como rodapé de algo? Ou acrescenta algum rodapé a 's'? O argumento 's' é uma entrada ou saída?

Em programação orientada por objetos a necessidade de usar argumentos de saída é praticamente inexistente porque a variável especial this é destinada a servir como argumento de saída. Em outras palavras, no exemplo acima o melhor seria a função ser invocada da seguinte forma:

report.appendFooter();

Ou seja, se uma função tiver que alterar o estado de algo, faça com que mude o estado do objeto que a contém.

Separação entre comando e consulta

Funções devem fazer algo ou responder algo, nunca os dois. Ou a função deve alterar o estado de um objeto ou deve retornar alguma informação sobre o objeto. Fazer as duas coisas em geral leva a confusões.

Considere a seguinte função:

public boolean set(String attribute, String value);

A função define o valor de um atributo e retorna true se houver sucesso e false se o atributo não existir.

O problema é que essa dupla finalidade (um comando e uma consulta na mesma função) gera ambiguidades do seguinte tipo. Imagine essa expressão:

if (set('username', 'bob')) { ... }

Quem estiver lendo não saberá se o teste está verificando se o username estava anteiormente definido como bob e, nesse caso, o teste será verdadeiro, ou se o resultado da definição do atributo username como bob é verdadeiro. Para evitar a ambiguidade, o melhor é separar o comando da consulta:

if (attributeExists('username')) {
    setAttribute('username', 'bob');
}

Prefira exceções a retornos de códigos de erro

Retornar diveros códigos de erro (error codes) em funções implica criação de subestruturas profundas e difícies de lidar. Além disso, se você criar um retorno de código de erro, o usuário que chamar a função terá que lidar com o erro imediatamente. Por outro lado, se você usar exceções (exceptions), o processamento do código de erro poderá ser feito separadamente:

try {
    deletePage(page);
    registry.deleteReference(page.name);
    configKeys.deleteKey(page.name.makeKey());
} catch (Exception e) {
    logger.log(e.getMessage());
}

Extraia blocos Try/Catch

Blocos try/catch já são feios por natureza. Eles misturam processamento normal com processamento de erros. O melhor é extrair o corpo do bloco try/catch em função própria.

public void delete(Page page) {
    try {
        deletePageAndAllReferences(page);
    } catch (Exception e) {
        logError(e);
    }
}

private void deletePageAndAllReferences(Page page) throws Exception {
    deletePage(page);
    registry.deleteReference(page.name);
    configKeys.deleteKey(page.name.makeKey());
}

private void logError(Exception e) {
    logger.log(e.getMessage());
}

Nesse exemplo, o bloco try/catch foi isolado na função delete. A função deletePageAndAllReferences trata somente do processamento para deletar. Essa seperação é importante para tornar o código mais fácil de ser lido e modificado.

Lidar com erro já é UMA coisa

Funções devem fazer apenas uma coisa. Gerenciar o erro já é uma coisa. Logo, funções que lidam com erro não devem fazer nada além disso. Assim, se a expressão try exsitir em uma função, deve ser a primeira linha dele e após o bloco não deve haver mais nada na função.

Não se repita (Don't Repeat Yourself)

É o princípio rei da programação. Muitas das técnicas e até mesmo toda a base da programação orientada por objeto tem como finalidade eliminar a repetição do código-fonte. A redundância ou duplicação de código é a prática mais maléfica que há na programação. Deve ser evitada a todo custo.

Comentários

Comentários, quando muito, são um mal necessário. Se as linguagens de programação fossem expressivas o suficiente ou se nós tivéssemos talento o suficiente para usar a linguagem de programação a fim de expressar nossas intenções, não precisaríamos de comentários no código-fonte.

O uso correto de comentários é apenas aquele que compensa a nossa incapacidade de nos expressarmos na forma de código. Logo, se você sentir a necessidade de escrever um comentário, pense duas vezes se não é possível melhorar o código de forma que a lingugem de programação exprima aquilo que seria escrito no comentário, de modo que ele não seja preciso.

Em geral, comentários mentem. Aliás, quanto mais antigos e não atualizados, mais desinformação e perda de tempo eles irão gerar. Assim, comentários imprecisos são muito pior do que nenhum comentário. Somente o código pode dizer o que ele realmente faz. Expresse-me por meio do código e não por meio de comentários.

As exceções que em geral admitem comentários são: comentários legais ou a respeito de licenças, comentários que revelam a intenção por trás de uma decisão de design, comentários que avisam programadores a respeito de consequências importantes ou específicas, comentários do tipo TODO (por fazer) - já que o destino deles é efetivamente desaparecer -, comentários que destacam a importância de algo que normalmente passaria por trivial e, obviamente, comentários a respeito da API pública (Javadoc, phpdoc etc.).

Veja no próximo post

Na próxima parte são analisados objetos e estrutudas de dados, manipulação de erros e o design de classes.


CLIQUE AQUI PARA VER A [PARTE 02 de 02] DAS BOAS PRÁTICAS.