A Arte de Escrever Programas Legíveis

Transcrição

1 A Arte de Escrever Programas Legíveis Técnicas simples e práticas para a elaboração de programas fáceis de serem lidos e entendidos Dustin Boswell Trevor Foucher Novatec

2 Authorized Portuguese translation of the English edition of titled The Art of Readable Code, First Edition ISBN Dustin Boswell and Trevor Foucher. This translation is published and sold by permission of O'Reilly Media, Inc., the owner of all rights to publish and sell the same. Tradução em português autorizada da edição em inglês da obra The Art of Readable Code, First Edition ISBN Dustin Boswell e Trevor Foucher. Esta tradução é publicada e vendida com a permissão da O'Reilly Media, Inc., detentora de todos os direitos para publicação e venda desta obra. Novatec Editora Ltda Todos os direitos reservados e protegidos pela Lei de 19/02/1998. É proibida a reprodução desta obra, mesmo parcial, por qualquer processo, sem prévia autorização, por escrito, do autor e da Editora. Editor: Rubens Prates Tradução: Rafael Zanolli Revisão técnica: Edgard Damiani Revisão gramatical: Débora Facin Editoração eletrônica: Carolina Kuwabata ISBN: Histórico de impressões: Fevereiro/2012 Primeira edição Novatec Editora Ltda. Rua Luís Antônio dos Santos São Paulo, SP Brasil Tel.: Fax: [email protected] Site: Twitter: twitter.com/novateceditora Facebook: facebook.com/novatec LinkedIn: linkedin.com/in/novatec Dados Internacionais de Catalogação na Publicação (CIP) (Câmara Brasileira do Livro, SP, Brasil) Boswell, Dustin A arte de escrever programas legíveis : técnicas simples e práticas para a elaboração de programas fáceis de serem lidos e entendidos / Dustin Boswell, Trevor Foucher ; [tradução Rafael Zanolli]. -- São Paulo : Novatec Editora ; Sebastopol, CA : O'Reilly, Título original: The art of readable code. ISBN Linguagem de programação (Computadores) 2. Software - Desenvolvimento 3. Teoria da codificação I. Foucher, Trevor. II. Título CDD Índices para catálogo sistemático: 1. Desenvolvimento de linguagens de programação : Computadores : Processamento de dados GRPM

3 Sumário Prefácio...11 Capítulo 1 Códigos devem ser fáceis de entender...15 O que torna um código melhor?...16 Teorema fundamental da legibilidade Menor é sempre melhor? Por acaso o tempo-para-entender entra em conflito com outros objetivos?...18 A parte difícil...18 Parte I Melhorias superficiais...19 Capítulo 2 Criação de nomes informativos...20 Escolha palavras específicas Evite nomes genéricos como tmp e retval...23 Prefira nomes concretos a nomes abstratos...26 Inclusão de informações extras a um nome...29 Qual deve ser o comprimento de um nome?...32 Utilize a formatação dos nomes para transmitir significado...34 Sumário...36 Capítulo 3 Nomes que não podem ser mal interpretados...37 Exemplo: Filter()...38 Exemplo: Clip(text, length)...38 Prefira min e max para limites (inclusivos)...39 Prefira first e last para intervalos inclusivos...40 Prefira begin e end para intervalos do tipo inclusivo/exclusivo...40 Nomenclatura de booleanos Atendendo às expectativas de seus usuários...42 Exemplo: avaliação de vários candidatos a nomes Sumário... 46

4 6 A Arte de Escrever Programas Legíveis Capítulo 4 Estética...47 Por que a estética é importante?...48 Reorganize quebras de linhas para que sejam consistentes e compactas...49 Utilize métodos para eliminar irregularidades...52 Utilize o alinhamento em colunas quando adequado...53 Escolha um ordenamento significativo e utilize-o de modo consistente...54 Organize declarações em blocos...55 Divida seus códigos em parágrafos...56 Estilo pessoal versus consistência...58 Sumário...59 Capítulo 5 Como saber o que comentar...60 O que NÃO devemos comentar Registre seus pensamentos...64 Coloque-se na posição do leitor...67 Considerações finais como superar seu bloqueio de escritor...72 Sumário...73 Capítulo 6 Crie comentários precisos e compactos...74 Mantenha seus comentários compactos...75 Evite pronomes ambíguos...75 Melhore referências imprecisas...76 Descreva o comportamento das funções de modo preciso...76 Utilize exemplos de entrada/saída para ilustrar situações confusas Declare a intenção de seu código...78 Comentários de parâmetros de função nomeados...79 Utilize palavras informativas...80 Sumário Parte II Simplificação de loops e lógica...82 Capítulo 7 Como facilitar a leitura do fluxo de controle...83 Ordem dos argumentos em condicionais...84 Ordem de blocos if/else...85 Expressão condicional?: (também conhecida como operador ternário )...87 Evite loops do/while...89 Retorno antecipado de uma função O infame goto Minimize o uso de aninhamentos...92

5 Sumário 7 Você consegue acompanhar o fluxo de execução?...95 Sumário Capítulo 8 Divisão de expressões gigantes...97 Variáveis de explicação...98 Variáveis de resumo...98 Uso das leis de De Morgan...99 Uso excessivo da lógica de curto-circuito Exemplo: Problemas com lógica complicada Divisão de expressões gigantes Outra forma criativa de simplificarmos expressões Sumário Capítulo 9 Variáveis e legibilidade Eliminação de variáveis Reduza o escopo de suas variáveis Prefira variáveis de gravação única Um exemplo final Sumário Parte III Reorganização de seu código Capítulo 10 Extração de subproblemas não relacionados Exemplo introdutório: findclosestlocation() Código utilitário puro Outros códigos de propósito geral Crie muitos códigos de propósito geral Funcionalidades específicas de projetos Simplificação de uma interface existente Remodele uma interface de acordo com suas necessidades Cuidado para não ir longe demais Sumário Capítulo 11 Uma tarefa de cada vez Tarefas podem ser pequenas Extração de valores de um objeto Um exemplo mais extenso Sumário

6 8 A Arte de Escrever Programas Legíveis Capítulo 12 Como transformar seus pensamentos em código Descreva sua lógica com clareza Vale a pena conhecer suas bibliotecas Aplicação desse método a problemas maiores Sumário Capítulo 13 Escreva menos código Não se preocupe em implementar esse recurso ele não será necessário Questione e divida seus requisitos Mantenha sua base de código pequena Esteja familiarizado com as bibliotecas à disposição Exemplo: Uso de ferramentas Unix em vez de codificação Sumário Parte V Tópicos selecionados Capítulo 14 Testes e legibilidade Facilite a leitura e a manutenção de seus testes O que há de errado com este teste? Como tornar esse teste mais legível Como tornar suas mensagens de erros mais legíveis Escolha de boas entradas de teste Nomenclatura de funções de teste O que havia de errado com aquele teste? Desenvolvimento compatível com testes Como perceber quando exageramos Sumário Capítulo 15 Projeto e implementação de um contador de minutos/horas O problema Definição da interface da classe Tentativa 1: uma solução ingênua Tentativa 2: projeto da esteira rolante Tentativa 3: um projeto com intervalos de tempo agrupados Comparação das três soluções Sumário...200

7 Sumário 9 Apêndice Leituras adicionais Livros que tratam da elaboração de códigos de alta qualidade Livros que tratam de vários tópicos de programação Livros de significado histórico Sobre os autores Índice remissivo...207

8 A Arte de Escrever Programas Legíveis Técnicas simples e práticas para a elaboração de programas fáceis de serem lidos e entendidos Dustin Boswell Trevor Foucher Novatec

9 Authorized Portuguese translation of the English edition of titled The Art of Readable Code, First Edition ISBN Dustin Boswell and Trevor Foucher. This translation is published and sold by permission of O'Reilly Media, Inc., the owner of all rights to publish and sell the same. Tradução em português autorizada da edição em inglês da obra The Art of Readable Code, First Edition ISBN Dustin Boswell e Trevor Foucher. Esta tradução é publicada e vendida com a permissão da O'Reilly Media, Inc., detentora de todos os direitos para publicação e venda desta obra. Novatec Editora Ltda Todos os direitos reservados e protegidos pela Lei de 19/02/1998. É proibida a reprodução desta obra, mesmo parcial, por qualquer processo, sem prévia autorização, por escrito, do autor e da Editora. Editor: Rubens Prates Tradução: Rafael Zanolli Revisão técnica: Edgard Damiani Revisão gramatical: Débora Facin Editoração eletrônica: Carolina Kuwabata ISBN: Histórico de impressões: Fevereiro/2012 Primeira edição Novatec Editora Ltda. Rua Luís Antônio dos Santos São Paulo, SP Brasil Tel.: Fax: [email protected] Site: Twitter: twitter.com/novateceditora Facebook: facebook.com/novatec LinkedIn: linkedin.com/in/novatec Dados Internacionais de Catalogação na Publicação (CIP) (Câmara Brasileira do Livro, SP, Brasil) Boswell, Dustin A arte de escrever programas legíveis : técnicas simples e práticas para a elaboração de programas fáceis de serem lidos e entendidos / Dustin Boswell, Trevor Foucher ; [tradução Rafael Zanolli]. -- São Paulo : Novatec Editora ; Sebastopol, CA : O'Reilly, Título original: The art of readable code. ISBN Linguagem de programação (Computadores) 2. Software - Desenvolvimento 3. Teoria da codificação I. Foucher, Trevor. II. Título CDD Índices para catálogo sistemático: 1. Desenvolvimento de linguagens de programação : Computadores : Processamento de dados GRPM

10 capítulo 1 Códigos devem ser fáceis de entender 15

11 16 A Arte de Escrever Programas Legíveis Nos últimos cinco anos, colecionamos centenas de exemplos de códigos malfeitos (na maioria dos casos, nossos mesmos) e analisamos o que eles tinham de errado e quais os princípios e técnicas que poderíamos utilizar para melhorá-los. O que percebemos é que todos os princípios têm origem em um único tema. I D E I A C H AV E Códigos devem ser fáceis de entender. Acreditamos que esse é o princípio mais importante que você pode utilizar para decidir como escrever seu código. Neste livro, mostraremos como aplicar esse princípio a diferentes aspectos de sua codificação diária. Antes de iniciarmos, vamos explicar essa ideia e justificar por que ela é tão importante. O que torna um código melhor? A maioria dos programadores (incluindo os autores) toma decisões de programação com base em instinto e intuição. Todos sabemos que um código assim: for (Node* node = list->head; node!= NULL; node = node->next) Print(node->data); é melhor do que outro como este: Node* node = list->head; if (node == NULL) return; while (node->next!= NULL) { Print(node->data); node = node->next; } if (node!= NULL) Print(node->data); (ainda que ambos os exemplos se comportem exatamente da mesma forma). Mas, muitas vezes, a escolha é mais difícil. Por exemplo, o código a seguir: return exponent >= 0? mantissa * (1 << exponent) : mantissa / (1 << -exponent); é melhor ou pior do que este? if (exponent >= 0) { return mantissa * (1 << exponent); } else { return mantissa / (1 << -exponent); }

12 Capítulo 1 Códigos devem ser fáceis de entender 17 A primeira versão é mais compacta, mas a segunda, menos intimidadora. Qual critério é mais importante? Em geral, como você decide a melhor forma de codificar algo? Teorema fundamental da legibilidade Depois de estudar muitos códigos de exemplo como o que vimos, chegamos à conclusão de que há uma métrica de legibilidade mais importante do que qualquer outra. Ela é tão importante que a chamamos de Teorema Fundamental da Legibilidade. I D E I A C H AV E Códigos devem ser escritos de modo a minimizar o tempo necessário para sua compreensão. O que queremos dizer com isso? Literalmente, se você escolhesse determinado colega seu e medisse quanto tempo ele leva para ler e entender seu código, esse tempo-para-entender seria a métrica teórica que deveríamos minimizar. E quando dizemos entender, utilizamos essa palavra em sentido muito abrangente. Para que alguém entenda completamente seu código, ele deve ser capaz de fazer alterações, encontrar bugs e compreender como ele interage com o restante do código. Agora, talvez você esteja pensando, Quem se importa se outra pessoa consegue entendê-lo? Eu sou o único utilizando o código! Ainda que você trabalhe sozinho, vale a pena perseguir esse objetivo. Essa outra pessoa pode ser você mesmo daqui a um ano, quando seu código já não lhe parecer mais familiar. E nunca se sabe alguém pode se juntar ao seu projeto, ou seu código descartável pode ser reutilizado em outro projeto. Menor é sempre melhor? Em termos gerais, quanto menos código você tiver de escrever para solucionar um problema, melhor (consulte o capítulo 13, Escreva menos código). Provavelmente demoraria menos para compreender uma classe de linhas do que uma de linhas. Mas ter menos linhas nem sempre é melhor! Muitas vezes, uma expressão como: assert((!(bucket = FindBucket(key)))!bucket->IsOccupied());

13 18 A Arte de Escrever Programas Legíveis é mais demorada de se entender do que uma versão com duas linhas: bucket = FindBucket(key); if (bucket!= NULL) assert(!bucket->isoccupied()); Do mesmo modo, um comentário pode fazer com que você entenda o código mais rapidamente, ainda que ele acrescente código ao arquivo: // Versão rápida de "hash = (65599 * hash) + c" hash = (hash << 6) + (hash << 16) - hash + c; Assim, ainda que utilizar menos linhas de código seja um bom objetivo, minimizar o tempo-para-entender é uma meta ainda melhor. Por acaso o tempo-para-entender entra em conflito com outros objetivos? Talvez você esteja pensando, Mas e outras preocupações, como tornar o código eficiente, bem projetado, fácil de testar e assim por diante? Objetivos como esses não entram, às vezes, em conflito com a meta de tornar o código fácil de entender? Verificamos que esses outros objetivos não interferem tanto assim no que buscamos. Mesmo em ambientes altamente otimizados, ainda temos como tornar os códigos bastante legíveis. Da mesma forma, tornar seu código fácil de entender muitas vezes faz com que ele também seja bem projetado e fácil de testar. O restante do livro discute como aplicar a ideia de fácil de entender em várias circunstâncias. No entanto, lembre-se de que, quando em dúvida, o Teorema Fundamental da Legibilidade supera qualquer outra regra ou princípio deste livro. Sabemos que alguns programadores têm uma necessidade compulsiva de corrigir qualquer código que não esteja fatorado perfeitamente. É sempre importante dar um passo atrás e perguntar, Este código é fácil de entender? Se afirmativo, provavelmente podemos avançar para outro código. A parte difícil Sim, sabemos que é necessário algum trabalho extra quando temos de pensar sempre se um usuário imaginário considera nosso código fácil de entender. Ao proceder dessa forma, você ativará uma parte de seu cérebro que talvez não esteja acostumada a funcionar durante a codificação. Mas, se você adotar esse objetivo (como nós o fizemos), estamos certos de que se tornará um programador melhor, sofrerá menos com bugs, terá mais orgulho de seu trabalho e produzirá códigos que todos adorarão utilizar. Por isso, vamos começar!