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
Authorized Portuguese translation of the English edition of titled The Art of Readable Code, First Edition ISBN 9780596802295 2012 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 9780596802295 2012 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. 2012. Todos os direitos reservados e protegidos pela Lei 9.610 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: 978-85-7522-294-2 Histórico de impressões: Fevereiro/2012 Primeira edição Novatec Editora Ltda. Rua Luís Antônio dos Santos 110 02460-000 São Paulo, SP Brasil Tel.: +55 11 2959-6529 Fax: +55 11 2950-8869 E-mail: novatec@novatec.com.br Site: www.novatec.com.br 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, 2012. Título original: The art of readable code. ISBN 978-85-7522-294-2 1. Linguagem de programação (Computadores) 2. Software - Desenvolvimento 3. Teoria da codificação I. Foucher, Trevor. II. Título. 12-01160 CDD-005.13 Índices para catálogo sistemático: 1. Desenvolvimento de linguagens de programação : Computadores : Processamento de dados 005.13 GRPM20120203
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... 17 Menor é sempre melhor?... 17 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... 21 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... 41 Atendendo às expectativas de seus usuários...42 Exemplo: avaliação de vários candidatos a nomes... 44 Sumário... 46
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... 61 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... 77 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... 81 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... 91 O infame goto... 91 Minimize o uso de aninhamentos...92
Sumário 7 Você consegue acompanhar o fluxo de execução?...95 Sumário... 96 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...100 Exemplo: Problemas com lógica complicada...101 Divisão de expressões gigantes... 103 Outra forma criativa de simplificarmos expressões... 105 Sumário...106 Capítulo 9 Variáveis e legibilidade...107 Eliminação de variáveis...108 Reduza o escopo de suas variáveis... 111 Prefira variáveis de gravação única...118 Um exemplo final...119 Sumário...121 Parte III Reorganização de seu código...122 Capítulo 10 Extração de subproblemas não relacionados...123 Exemplo introdutório: findclosestlocation()... 124 Código utilitário puro... 126 Outros códigos de propósito geral... 127 Crie muitos códigos de propósito geral... 129 Funcionalidades específicas de projetos... 130 Simplificação de uma interface existente...131 Remodele uma interface de acordo com suas necessidades... 132 Cuidado para não ir longe demais... 133 Sumário... 134 Capítulo 11 Uma tarefa de cada vez...135 Tarefas podem ser pequenas... 137 Extração de valores de um objeto... 139 Um exemplo mais extenso... 143 Sumário... 146
8 A Arte de Escrever Programas Legíveis Capítulo 12 Como transformar seus pensamentos em código...147 Descreva sua lógica com clareza... 148 Vale a pena conhecer suas bibliotecas... 149 Aplicação desse método a problemas maiores... 150 Sumário... 154 Capítulo 13 Escreva menos código...156 Não se preocupe em implementar esse recurso ele não será necessário... 157 Questione e divida seus requisitos... 157 Mantenha sua base de código pequena... 159 Esteja familiarizado com as bibliotecas à disposição...161 Exemplo: Uso de ferramentas Unix em vez de codificação... 163 Sumário...164 Parte V Tópicos selecionados...165 Capítulo 14 Testes e legibilidade...166 Facilite a leitura e a manutenção de seus testes... 167 O que há de errado com este teste?... 167 Como tornar esse teste mais legível...168 Como tornar suas mensagens de erros mais legíveis... 172 Escolha de boas entradas de teste...174 Nomenclatura de funções de teste... 176 O que havia de errado com aquele teste?... 178 Desenvolvimento compatível com testes... 179 Como perceber quando exageramos...181 Sumário... 182 Capítulo 15 Projeto e implementação de um contador de minutos/horas...183 O problema... 184 Definição da interface da classe... 184 Tentativa 1: uma solução ingênua... 188 Tentativa 2: projeto da esteira rolante...191 Tentativa 3: um projeto com intervalos de tempo agrupados... 194 Comparação das três soluções... 199 Sumário...200
Sumário 9 Apêndice Leituras adicionais...201 Livros que tratam da elaboração de códigos de alta qualidade...202 Livros que tratam de vários tópicos de programação...203 Livros de significado histórico...204 Sobre os autores...205 Índice remissivo...207
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
Authorized Portuguese translation of the English edition of titled The Art of Readable Code, First Edition ISBN 9780596802295 2012 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 9780596802295 2012 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. 2012. Todos os direitos reservados e protegidos pela Lei 9.610 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: 978-85-7522-294-2 Histórico de impressões: Fevereiro/2012 Primeira edição Novatec Editora Ltda. Rua Luís Antônio dos Santos 110 02460-000 São Paulo, SP Brasil Tel.: +55 11 2959-6529 Fax: +55 11 2950-8869 E-mail: novatec@novatec.com.br Site: www.novatec.com.br 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, 2012. Título original: The art of readable code. ISBN 978-85-7522-294-2 1. Linguagem de programação (Computadores) 2. Software - Desenvolvimento 3. Teoria da codificação I. Foucher, Trevor. II. Título. 12-01160 CDD-005.13 Índices para catálogo sistemático: 1. Desenvolvimento de linguagens de programação : Computadores : Processamento de dados 005.13 GRPM20120203
capítulo 1 Códigos devem ser fáceis de entender 15
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); }
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 2.000 linhas do que uma de 5.000 linhas. Mas ter menos linhas nem sempre é melhor! Muitas vezes, uma expressão como: assert((!(bucket = FindBucket(key)))!bucket->IsOccupied());
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!