Insights de código limpo – Formatação

Nos insights de código limpo de hoje trago um assunto com o qual me preocupo bastante quando estou escrevendo código, a formatação. Neste capítulo de Código Limpo, tio Bob explica que um código bem formatado ajuda na legibilidade e também demonstra profissionalismo por parte de quem o escreveu, pois ajuda outros profissionais a lerem tal código de forma fácil quando alguma manutenção é necessária. Além disso, Bob enfatiza que código bem formatado diz respeito a comunicação.

clean-code-formatting

Alguns pontos importantes a considerar quando se fala de formatação de código são:

Formatação vertical

Arquivos pequenos são normalmente mais fácies de se entender do que arquivos grandes.

A metáfora do jornal

No topo de uma página de jornal está o título, o qual lhe fará decidir se quer ou não ler sobre tal assunto.  O primeiro parágrafo lhe trará uma sinopse da história como um todo, escondendo detalhes e abrangendo conceitos de maneira geral. E quando você continua, então tem acesso a todos os detalhes, datas, nomes, citações, créditos e outras minúcias.

Com código o ideal é qua seja algo como isso. O nome deve ser simples e explicativo. A parte mais superior do código deve prover uma ideia de alto nível dos conceitos e algoritmos. E os detalhes devem ir aumentando assim que você vai rolando o arquivo para baixo, até chegar às funções de mais baixo nível.

Abertura vertical entre conceitos

Aqui a regra é simples, invista algumas linhas em branco entre conceitos para tornar o código mais legível.

Vejas os seguintes exemplos e perceba como o primeiro é mais fácil de ler:

var SearchPage = function() {

  this.searchField = $('#search');
  this.imLuckButton = $('#search-button');

  this.get = function() {
    browser.get('search');
  };

  this.search = function(text) {
    this.searchField.sendKeys(text);
    this.imLuckButton.click();
  };
 
};

module.exports = new SearchPage();
var SearchPage = function() {
  this.searchField = $('#search');
  this.imLuckButton = $('#search-button');
  this.get = function() {
    browser.get('search');
  };
  this.search = function(text) {
    this.searchField.sendKeys(text);
    this.imLuckButton.click();
  };
};
module.exports = new SearchPage();

Apesar de o segundo código ter menos linhas, não existe uma separação de conceitos, tal como a definição dos atributos e métodos da função principal, portanto, as vezes vale a pena ter algumas linhas a mais no código, mas que ajudarão na leitura do mesmo.

Densidade vertical

A densidade vertical ajuda na compreensão do código sem a necessidade de muitos movimentos de olhos e cabeça. Você “bate o olho” no código e já sabe o que ele faz.

Distância vertical

Conceitos relacionados devem estar verticalmente próximos uns dos outros.

Declaração de variáveis

Variáveis devem ser declaradas o mais próximo possível de seu uso. Como as funções devem ser curtas, as variáveis devem ser exibidas no topo de cada função.

Variáveis de instância

Variáveis de instância devem ser declaradas no topo das classes e isso não deve aumentar a distância vertical das variáveis, pois, em uma classe bem projetada elas serão utilizadas em muitos, senão em todos os métodos da classe.

Funções dependentes

Se uma função depende de outra, elas devem estar verticalmente próximas e a função que chama deve estar acima da função chamada. Isso provê um fluxo natural na leitura do código.

Afinidade conceitual

Certos bits de código precisam estar muito próximos de outros, pois, possuem certa afinidade conceitual. Quanto mais forte esta afinidade, menos distância vertical deve haver entre eles.

Ordenação vertical

No geral, queremos que as chamadas de funções dependentes apontem para baixo, ou seja, uma função que é chamada deve estar abaixo da função que a chama.

É como em um artigo de jornal, onde esperamos que os conceitos mais importantes venham primeiro e com o mínimo de detalhes, para que então os detalhes de mais baixo nível venham no final.

Formatação horizontal

O ideal é que não haja a necessidade de rolagem horizontal para a leitura de código, porém, devido a diferentes tamanhos de monitores, o ideal é que utilizemos o bom senso.

Abertura horizontal e densidade

Aqui prefiro explicar com um caso prático. Veja o seguinte código:

this.create = function(name) {
  this.get();
  browser.wait(this.nameField.isDisplayed);
  this.nameField.sendKeys(name);
  this.saveButton.click();
};

No código acima, utilizo espaços em branco para demonstrar que this.create recebe uma função. Isso deixa claro dois elementos distintos, o do lado esquerdo e o do lado direito. Os espaços tornam esta separação óbvia. Ao mesmo tempo, não utilizei espaços em branco entre a palavra function e a abertura de parênteses, isto, pois a função e seus argumentos são extremamente relacionados.

Alinhamento horizontal

É muito comum encontrar códigos como este:

this.emailField             = $'(#edit-mail');
this.passwordField          = $('#edit-pass');
this.confirmPasswordField   = $('#edit-confirm-pass');
this.createNewAccountButton = $('#create-account-btn');

Porém, tal tipo de alinhamento não tem utilidade. Este tipo de alinhamento parece enfatizar coisas erradas e leva os olhos para longe da verdadeira intenção do código.

Na escola de pensamento do tio Bob, sugere-se que o mesmo código seja escrito da seguinte forma, assim, o código pode ser lido com mais naturalidade:

this.emailField = $'(#edit-mail');
this.passwordField = $('#edit-pass');
this.confirmPasswordField = $('#edit-confirm-pass');
this.createNewAccountButton = $('#create-account-btn');

Identação

Um bom exemplo sempre que o assunto é identação é a linguagem Python, na qual a identação faz parte de sua sintaxe, a qual prima pela legibilidade e padronização do código. Em Python, um código sem a identação correta não pode nem mesmo ser interpretado.

A lição aqui é: a identação ajuda na leitura do código, ajuda a entender o que faz parte de qual contexto e questões relacionadas a recursividade do código. Uma boa identação ajuda na identificação instantânea de variáveis, construtores, métodos, etc.

Quebrando a identação

Em alguns casos podemos quebrar a regra da identação, como em uma instrução if curta, em loops pequenos, ou em funções muito curtas.  Veja:

function run() { this.runButton.click(); }

Ainda assim, não é feio identar códigos como esse, pois isso os tornará ainda mais legíveis. Veja:

function run() { 
  this.runButton.click();
}

As regras do time

Desenvolvedores que trabalham em time devem estar em comum acordo sobre regras de formatação simples. Não se espera que códigos de um mesmo time pareçam ter sido escritos por pessoas  cujas quais utilizam cada uma suas próprias regras de formatação de código. Isso não está só relacionado a como escrevemos código, mas também sobre respeito, ou seja, sobre o respeito que temos pelos outros membros do time.

E aí, está gostando da série? Deixe um comentário.

Anúncios

Um comentário em “Insights de código limpo – Formatação

Deixe um comentário

Preencha os seus dados abaixo ou clique em um ícone para log in:

Logotipo do WordPress.com

Você está comentando utilizando sua conta WordPress.com. Sair / Alterar )

Imagem do Twitter

Você está comentando utilizando sua conta Twitter. Sair / Alterar )

Foto do Facebook

Você está comentando utilizando sua conta Facebook. Sair / Alterar )

Foto do Google+

Você está comentando utilizando sua conta Google+. Sair / Alterar )

Conectando a %s