Anotações Capítulo 5: Formatting

• “Você deve tomar conta para que seu código fique bem formatado”;
• Escolha regras simples e aplique de forma consistente.
• Em equipe, todos devem concordar com uma única série de regras de formatação.

Objetivo da formatação

• A formatação de código é importante.
• Serve como comunicação.
• Legibilidade do código terá um grande efeito em todas as mudanças futuras.

Formatação vertical

• Há uma grande diversidade de tamanhos e diferenças de estilo.
• As linhas verticais mostram os comprimentos mínimo e máximo.
• Arquivos pequenos costumam ser mais fáceis de se entender do que os grandes.

A metáfora do jornal

• “No topo você espera ver uma manchete que lhe diz do que se trata a história e lhe permite decidir se deseja ou não ler”.
• Primeiro parágrafo é a sinopse da história.
• O demais detalhes vem no decorrer da leitura.
• Queremos que o código fonte seja como artigo de jornal.

Espaçamento vertical entre conceitos

• Há linhas em branco que separam a declaração e a importação do pacote e cada uma das funções.
• “Cada linha em branco indica visualmente a separação entre conceitos”.
• Retirar as linhas em branco, gera um efeito muito ruim na legibilidade do código.

Continuidade vertical

• A continuidade vertical indica uma associação íntima.
• Linhas de código que estão intimamente relacionadas devem aparecer verticalmente unidas.
• Comentários inúteis quebram essa intimidade de duas variáveis:

public class ReporterConfig { /** * The class name of the reporter listener */ private String m_className; /** * The properties of the reporter listener */ private List<Property> m_properties = new ArrayList<Property>(); public void addProperty(Property property) { m_properties.add(property); } 

• Removendo os comentários fica mais fácil de ler:

public class ReporterConfig { private String m_className; private List<Property> m_properties = new ArrayList<Property>(); public void addProperty(Property property) { m_properties.add(property); } } 

Esse último exemplo, o código cabe numa única visão, podemos compreender todo o método sem ter que mover a cabeça ou os olhos.

Distância vertical

• Os conceitos intimamente relacionados para conceitos em arquivos separados.
• Não devemos separar em arquivos distintos conceitos intimamente relacionados, a menos que tenha uma razão muito boa.
• A separação vertical deles deve ser uma medida do quão importante eles são para a inteligibilidade um do outro.
• Devemos declarar variáveis o mais próximo possível de onde serão usadas”.
• Exemplo: Devemos declarar variáveis de controle para loops dentro da estrutura de iteração:

public int countTestCases() { int count= 0; for (Test each : tests) count += each.countTestCases(); return count; } 

• Em alguns casos pode-se declarar uma variável no início de um bloco ou logo depois de um loop em uma função longa:

for (XmlTest test : m_suite.getTests()) { TestRunner tr = m_runnerFactory.newTestRunner(this, test); tr.addListener(m_textReporter); m_testRunners.add(tr); invoker = tr.getInvoker(); for (ITestNGMethod m : tr.getBeforeSuiteMethods()) { beforeSuiteMethods.put(m.getMethod(), m); } for (ITestNGMethod m : tr.getAfterSuiteMethods()) { afterSuiteMethods.put(m.getMethod(), m); } } 

• Variáveis de Instância: Devemos declarar as variáveis de instância no início da classe. Isso não deve aumentar a distância vertical entre tais variáveis, elas serão usadas por muitos, senão todos, os métodos da classe.
• O importante é que as variáveis de instância sejam declaradas em um local bem conhecido. Todos devem saber onde buscar as declarações.
• Funções dependentes: Se uma função chama outra, elas devem ficar verticalmente próximas. Assim, a que chama deve ficar acima da que for chamada. Isso dá um fluxo natural ao programa.
• Assim, os leitores poderão confiar que as declarações daquelas funções virão logo em seguida.
• Afinidade conceitual: Quanto maior a afinidade, menor deve ser a distância entre eles.
• A afinidade se baseia numa dependência direta. Uma função chamando outra. Uma função usando uma variável.
• Um grupo de funções que efetuam uma operação parecida cria uma afinidade. Exemplo:

public class Assert { static public void assertTrue(String message, boolean condition) { if (!condition) fail(message); } static public void assertTrue(boolean condition) { assertTrue(null, condition); } static public void assertFalse(String message, boolean condition) { assertTrue(message, !condition); } static public void assertFalse(boolean condition) { assertFalse(null, condition); } ... 

Essas funções possuem uma afinidade conceitual forte, pois compartilham de uma mesma convenção de nomes e efetuam variações de uma mesma tarefa. Bem como o fato de uma chamar a outra.

Ordenação vertical

• Desejamos que as chamadas das dependências da função apontem para baixo;
• No caso, “a função chamada deve ficar embaixo da que a chama”;
• Cria um fluxo natural para baixo no módulo do código-fonte, de um nível maior para um menor.
• Assim os detalhes de baixo nível venham por último.

Formatação horizontal

• “Devemos nos esforçar para manter nossas linhas curtas”;
• O antigo limite de 80 de Hollerith é arbitrário;
• Com 100 linhas ou 120 ainda é aceitável, porém ultrapassar 120 caracteres é uma falta de cuidado;

Espaçamento e continuidade horizontal

• Operadores de atribuição entre espaços em branco:

int lineSize = line.length(); 

Essas instruções tem dois lados distintos, o lado esquerdo e o lado direito. Assim, os espaços tornam essa separação óbvia.

• Porém não coloque espaços entre os nomes das funções e os parênteses de abertura. Isso porque a função e seus parâmetros estão intimamente relacionados;
• Bem como separar os parâmetros entre parênteses na chamada da função realçar a vírgula e mostram que estão separados;
• Espaço em branco entre operadores é para destacar a prioridade dos mesmo;

Alinhamento horizontal

• Esse tipo de alinhamento não é prático;
• Parece enfatizar as coisas erradas e afasta o propósito real;
• As ferramentas de reformatação automática geralmente eliminam esse tipo de alinhamento;
• É melhor não usar esse tipo de alinhamento;
• Se tiver listas longas que precisam ser alinhadas, “o problema está no tamanho das listas”e não na falta de alinhamento;

Indentação

• Um código-fonte é mais como uma hierarquia do que algo esquematizado;
• Informações pertinentes ao arquivo, classes individuais dentro do arquivo, aos métodos das classes, aos blocos dentro dos métodos.
• Cada nível dessa hierarquia é um escopo.
• E para tornar visível essa hierarquia indentamos o código.
• Os programadores dependem bastante dessa indentação.
• Elas alinham visualmente na esquerda as linhas para ver em qual escopo eles estão.
• Assim a navegação e a compreensão do código para o programador é facilitada, ele sempre vai procurar a declaração variáveis mais a esquerda, etc.
• A mesma versão de um código sem indentação é quase incompreensível.
• Ignorando a indentação: Podemos querer não fazer a indentação mas no fim voltamos e fazemos, é uma necessidade.

Escopos minúsculos

• Estruturas while ou for minúsculas, é complicado para uma boa indentação.

Regra de equipes

• Todo programador tem suas regras de formatação prediletas;
• Mais em uma equipe, as regras são dela;
• A equipe deve escolher um único estilo de formatação e todos devem usá-lo;
• Assim o código tem estilo consistente;
• O leitor precisa poder confiar que as formatações que ele vir em uma arquivo-fonte terão o mesmo significado nos outros.

Regras de formatação do Uncle Bob

• Considere este um exemplo de como o código torna o melhor documento padrão de codificação:

public class CodeAnalyzer implements JavaFileAnalysis { private int lineCount; private int maxLineWidth; private int widestLineNumber; private LineWidthHistogram lineWidthHistogram; private int totalChars; public CodeAnalyzer() { lineWidthHistogram = new LineWidthHistogram(); } public static List<File> findJavaFiles(File parentDirectory) { List<File> files = new ArrayList<File>(); findJavaFiles(parentDirectory, files); return files; } private static void findJavaFiles(File parentDirectory, List<File> files) { for (File file : parentDirectory.listFiles()) { if (file.getName().endsWith(".java")) files.add(file); else if (file.isDirectory()) findJavaFiles(file, files); } } public void analyzeFile(File javaFile) throws Exception { BufferedReader br = new BufferedReader(new FileReader(javaFile)); String line; while ((line = br.readLine()) != null) measureLine(line); } private void measureLine(String line) { lineCount++; int lineSize = line.length(); totalChars += lineSize; lineWidthHistogram.addLine(lineSize, lineCount); recordWidestLine(lineSize); } private void recordWidestLine(int lineSize) { if (lineSize > maxLineWidth) { maxLineWidth = lineSize; widestLineNumber = lineCount; } } public int getLineCount() { return lineCount; } public int getMaxLineWidth() { return maxLineWidth; } public int getWidestLineNumber() { return widestLineNumber; } <restante do código> }