From c9a251b6a8f680acc93c6db32e7e17426f327a19 Mon Sep 17 00:00:00 2001 From: Dickson Souza <36424026+disouzam@users.noreply.github.com> Date: Sat, 11 May 2024 17:31:32 -0300 Subject: [PATCH] added thing_16 in pt_br --- pt_br/SUMMARY.md | 200 +++++++++++++++++++-------------------- pt_br/thing_16/README.md | 15 +++ 2 files changed, 115 insertions(+), 100 deletions(-) create mode 100644 pt_br/thing_16/README.md diff --git a/pt_br/SUMMARY.md b/pt_br/SUMMARY.md index 1c951b4..b0bef42 100644 --- a/pt_br/SUMMARY.md +++ b/pt_br/SUMMARY.md @@ -1,100 +1,100 @@ -# Summary - -* [Introdução](README.md) -1. [Aja com Prudência](thing_01/README.md) -1. [Aplique princípios de programação funcional](thing_02/README.md) -1. [Pergunte-se "O que o usuário faria?" (Você não é o usuário)](thing_03/README.md) -1. [Automatize seu padrão de código](thing_04/README.md) -1. [A beleza está na simplicidade](thing_05/README.md) -1. [Antes que você refatore](thing_06/README.md) -1. [Esteja ciente da sua parte no todo](thing_07/README.md) -1. [A regra do escoteiro](thing_08/README.md) -1. [Confira seu próprio código antes de acusar os outros](thing_09/README.md) -1. [Escolha suas ferramentas com cuidado](thing_10/README.md) -1. [Desenvolva usando a linguagem do domínio de negócios](thing_11/README.md) -1. [Código é Design](thing_12/README.md) -1. [O layout do código é importante](thing_13/README.md) -1. [Revisão de código](thing_14/README.md) -1. [Programando com um motivo](thing_15/README.md) -1. [A Comment on Comments](thing_16/README.md) -1. [Comment Only What the Code Cannot Say](thing_17/README.md) -1. [Continuous Learning](thing_18/README.md) -1. [Convenience Is not an -ility](thing_19/README.md) -1. [Deploy Early and Often](thing_20/README.md) -1. [Distinguish Business Exceptions from Technical](thing_21/README.md) -1. [Do Lots of Deliberate Practice](thing_22/README.md) -1. [Domain-Specific Languages](thing_23/README.md) -1. [Don't Be Afraid to Break Things](thing_24/README.md) -1. [Don't Be Cute with Your Test Data](thing_25/README.md) -1. [Don't Ignore that Error!](thing_26/README.md) -1. [Don't Just Learn the Language, Understand its Culture](thing_27/README.md) -1. [Don't Nail Your Program into the Upright Position](thing_28/README.md) -1. [Don't Rely on "Magic Happens Here"](thing_29/README.md) -1. [Don't Repeat Yourself](thing_30/README.md) -1. [Don't Touch that Code!](thing_31/README.md) -1. [Encapsulate Behavior, not Just State](thing_32/README.md) -1. [Floating-point Numbers Aren't Real](thing_33/README.md) -1. [Fulfill Your Ambitions with Open Source](thing_34/README.md) -1. [The Golden Rule of API Design](thing_35/README.md) -1. [The Guru Myth](thing_36/README.md) -1. [Hard Work Does not Pay Off](thing_37/README.md) -1. [How to Use a Bug Tracker](thing_38/README.md) -1. [Improve Code by Removing It](thing_39/README.md) -1. [Install Me](thing_40/README.md) -1. [Inter-Process Communication Affects Application Response Time](thing_41/README.md) -1. [Keep the Build Clean](thing_42/README.md) -1. [Know How to Use Command-line Tools](thing_43/README.md) -1. [Know Well More than Two Programming Languages](thing_44/README.md) -1. [Know Your IDE](thing_45/README.md) -1. [Know Your Limits](thing_46/README.md) -1. [Know Your Next Commit](thing_47/README.md) -1. [Large Interconnected Data Belongs to a Database](thing_48/README.md) -1. [Learn Foreign Languages](thing_49/README.md) -1. [Learn to Estimate](thing_50/README.md) -1. [Learn to Say "Hello, World"](thing_51/README.md) -1. [Let Your Project Speak for Itself](thing_52/README.md) -1. [The Linker Is not a Magical Program](thing_53/README.md) -1. [The Longevity of Interim Solutions](thing_54/README.md) -1. [Make Interfaces Easy to Use Correctly and Hard to Use Incorrectly](thing_55/README.md) -1. [Make the Invisible More Visible](thing_56/README.md) -1. [Message Passing Leads to Better Scalability in Parallel Systems](thing_57/README.md) -1. [A Message to the Future](thing_58/README.md) -1. [Missing Opportunities for Polymorphism](thing_59/README.md) -1. [News of the Weird: Testers Are Your Friends](thing_60/README.md) -1. [One Binary](thing_61/README.md) -1. [Only the Code Tells the Truth](thing_62/README.md) -1. [Own (and Refactor) the Build](thing_63/README.md) -1. [Pair Program and Feel the Flow](thing_64/README.md) -1. [Prefer Domain-Specific Types to Primitive Types](thing_65/README.md) -1. [Prevent Errors](thing_66/README.md) -1. [The Professional Programmer](thing_67/README.md) -1. [Put Everything Under Version Control](thing_68/README.md) -1. [Put the Mouse Down and Step Away from the Keyboard](thing_69/README.md) -1. [Read Code](thing_70/README.md) -1. [Read the Humanities](thing_71/README.md) -1. [Reinvent the Wheel Often](thing_72/README.md) -1. [Resist the Temptation of the Singleton Pattern](thing_73/README.md) -1. [The Road to Performance Is Littered with Dirty Code Bombs](thing_74/README.md) -1. [Simplicity Comes from Reduction](thing_75/README.md) -1. [The Single Responsibility Principle](thing_76/README.md) -1. [Start from Yes](thing_77/README.md) -1. [Step Back and Automate, Automate, Automate](thing_78/README.md) -1. [Take Advantage of Code Analysis Tools](thing_79/README.md) -1. [Test for Required Behavior, not Incidental Behavior](thing_80/README.md) -1. [Test Precisely and Concretely](thing_81/README.md) -1. [Test While You Sleep (and over Weekends)](thing_82/README.md) -1. [Testing Is the Engineering Rigor of Software Development](thing_83/README.md) -1. [Thinking in States](thing_84/README.md) -1. [Two Heads Are Often Better than One](thing_85/README.md) -1. [Two Wrongs Can Make a Right (and Are Difficult to Fix)](thing_86/README.md) -1. [Ubuntu Coding for Your Friends](thing_87/README.md) -1. [The Unix Tools Are Your Friends](thing_88/README.md) -1. [Use the Right Algorithm and Data Structure](thing_89/README.md) -1. [Verbose Logging Will Disturb Your Sleep](thing_90/README.md) -1. [WET Dilutes Performance Bottlenecks](thing_91/README.md) -1. [When Programmers and Testers Collaborate](thing_92/README.md) -1. [Write Code as If You Had to Support It for the Rest of Your Life](thing_93/README.md) -1. [Write Small Functions Using Examples](thing_94/README.md) -1. [Write Tests for People](thing_95/README.md) -1. [You Gotta Care about the Code](thing_96/README.md) -1. [Your Customers Do not Mean What They Say](thing_97/README.md) +# Summary + +* [Introdução](README.md) +1. [Aja com Prudência](thing_01/README.md) +1. [Aplique princípios de programação funcional](thing_02/README.md) +1. [Pergunte-se "O que o usuário faria?" (Você não é o usuário)](thing_03/README.md) +1. [Automatize seu padrão de código](thing_04/README.md) +1. [A beleza está na simplicidade](thing_05/README.md) +1. [Antes que você refatore](thing_06/README.md) +1. [Esteja ciente da sua parte no todo](thing_07/README.md) +1. [A regra do escoteiro](thing_08/README.md) +1. [Confira seu próprio código antes de acusar os outros](thing_09/README.md) +1. [Escolha suas ferramentas com cuidado](thing_10/README.md) +1. [Desenvolva usando a linguagem do domínio de negócios](thing_11/README.md) +1. [Código é Design](thing_12/README.md) +1. [O layout do código é importante](thing_13/README.md) +1. [Revisão de código](thing_14/README.md) +1. [Programando com um motivo](thing_15/README.md) +1. [Um comentário sobre os comentários](thing_16/README.md) +1. [Comment Only What the Code Cannot Say](thing_17/README.md) +1. [Continuous Learning](thing_18/README.md) +1. [Convenience Is not an -ility](thing_19/README.md) +1. [Deploy Early and Often](thing_20/README.md) +1. [Distinguish Business Exceptions from Technical](thing_21/README.md) +1. [Do Lots of Deliberate Practice](thing_22/README.md) +1. [Domain-Specific Languages](thing_23/README.md) +1. [Don't Be Afraid to Break Things](thing_24/README.md) +1. [Don't Be Cute with Your Test Data](thing_25/README.md) +1. [Don't Ignore that Error!](thing_26/README.md) +1. [Don't Just Learn the Language, Understand its Culture](thing_27/README.md) +1. [Don't Nail Your Program into the Upright Position](thing_28/README.md) +1. [Don't Rely on "Magic Happens Here"](thing_29/README.md) +1. [Don't Repeat Yourself](thing_30/README.md) +1. [Don't Touch that Code!](thing_31/README.md) +1. [Encapsulate Behavior, not Just State](thing_32/README.md) +1. [Floating-point Numbers Aren't Real](thing_33/README.md) +1. [Fulfill Your Ambitions with Open Source](thing_34/README.md) +1. [The Golden Rule of API Design](thing_35/README.md) +1. [The Guru Myth](thing_36/README.md) +1. [Hard Work Does not Pay Off](thing_37/README.md) +1. [How to Use a Bug Tracker](thing_38/README.md) +1. [Improve Code by Removing It](thing_39/README.md) +1. [Install Me](thing_40/README.md) +1. [Inter-Process Communication Affects Application Response Time](thing_41/README.md) +1. [Keep the Build Clean](thing_42/README.md) +1. [Know How to Use Command-line Tools](thing_43/README.md) +1. [Know Well More than Two Programming Languages](thing_44/README.md) +1. [Know Your IDE](thing_45/README.md) +1. [Know Your Limits](thing_46/README.md) +1. [Know Your Next Commit](thing_47/README.md) +1. [Large Interconnected Data Belongs to a Database](thing_48/README.md) +1. [Learn Foreign Languages](thing_49/README.md) +1. [Learn to Estimate](thing_50/README.md) +1. [Learn to Say "Hello, World"](thing_51/README.md) +1. [Let Your Project Speak for Itself](thing_52/README.md) +1. [The Linker Is not a Magical Program](thing_53/README.md) +1. [The Longevity of Interim Solutions](thing_54/README.md) +1. [Make Interfaces Easy to Use Correctly and Hard to Use Incorrectly](thing_55/README.md) +1. [Make the Invisible More Visible](thing_56/README.md) +1. [Message Passing Leads to Better Scalability in Parallel Systems](thing_57/README.md) +1. [A Message to the Future](thing_58/README.md) +1. [Missing Opportunities for Polymorphism](thing_59/README.md) +1. [News of the Weird: Testers Are Your Friends](thing_60/README.md) +1. [One Binary](thing_61/README.md) +1. [Only the Code Tells the Truth](thing_62/README.md) +1. [Own (and Refactor) the Build](thing_63/README.md) +1. [Pair Program and Feel the Flow](thing_64/README.md) +1. [Prefer Domain-Specific Types to Primitive Types](thing_65/README.md) +1. [Prevent Errors](thing_66/README.md) +1. [The Professional Programmer](thing_67/README.md) +1. [Put Everything Under Version Control](thing_68/README.md) +1. [Put the Mouse Down and Step Away from the Keyboard](thing_69/README.md) +1. [Read Code](thing_70/README.md) +1. [Read the Humanities](thing_71/README.md) +1. [Reinvent the Wheel Often](thing_72/README.md) +1. [Resist the Temptation of the Singleton Pattern](thing_73/README.md) +1. [The Road to Performance Is Littered with Dirty Code Bombs](thing_74/README.md) +1. [Simplicity Comes from Reduction](thing_75/README.md) +1. [The Single Responsibility Principle](thing_76/README.md) +1. [Start from Yes](thing_77/README.md) +1. [Step Back and Automate, Automate, Automate](thing_78/README.md) +1. [Take Advantage of Code Analysis Tools](thing_79/README.md) +1. [Test for Required Behavior, not Incidental Behavior](thing_80/README.md) +1. [Test Precisely and Concretely](thing_81/README.md) +1. [Test While You Sleep (and over Weekends)](thing_82/README.md) +1. [Testing Is the Engineering Rigor of Software Development](thing_83/README.md) +1. [Thinking in States](thing_84/README.md) +1. [Two Heads Are Often Better than One](thing_85/README.md) +1. [Two Wrongs Can Make a Right (and Are Difficult to Fix)](thing_86/README.md) +1. [Ubuntu Coding for Your Friends](thing_87/README.md) +1. [The Unix Tools Are Your Friends](thing_88/README.md) +1. [Use the Right Algorithm and Data Structure](thing_89/README.md) +1. [Verbose Logging Will Disturb Your Sleep](thing_90/README.md) +1. [WET Dilutes Performance Bottlenecks](thing_91/README.md) +1. [When Programmers and Testers Collaborate](thing_92/README.md) +1. [Write Code as If You Had to Support It for the Rest of Your Life](thing_93/README.md) +1. [Write Small Functions Using Examples](thing_94/README.md) +1. [Write Tests for People](thing_95/README.md) +1. [You Gotta Care about the Code](thing_96/README.md) +1. [Your Customers Do not Mean What They Say](thing_97/README.md) diff --git a/pt_br/thing_16/README.md b/pt_br/thing_16/README.md new file mode 100644 index 0000000..431971e --- /dev/null +++ b/pt_br/thing_16/README.md @@ -0,0 +1,15 @@ +# Um comentário sobre os comentários + +Na minha primeira matéria na graduação, meu professor entregou duas folhas de papel com códigos BASIC. No quadro, a tarefa dizia "Escreva um programa para ler a entrada de 10 jogos de boliche e retorne a média." Depois disso o professor saiu da sala. Quão difícil pode ser isso? Eu não lembro da minha solução final mas estou certo que tinha um loop `FOR/NEXT' nele e não devia ser mais do que 15 linhas no total. Folhas de código - para vocês mais novos que estão lendo isso, sim, nós usávamos escrever o código à mão antes de realmente entrar com ele no computador - permitiam cerca de 70 linhas de código cada. Eu estava muito confuso sobre o porquê o professor teria nos dado duas folhas de papel. Visto que minha escrita à não sempre havia sido muito ruim, eu usei a segunda folha para reescrever meu código de forma mais organizada, na esperança de ganhar alguns pontos extras pelo estilo. + +Tamanha foi minha surpresa, quando recebi o trabalho de volta no início da próxima aula, eu recebi uma nota apenas um pouco maior que a mínima para aprovação. (Isso viria a ser um presságio para mim para o resto do meu tempo na graduação.) Passei o olho no topo da folha que havia reescrito o código, e tinha a pergunta "Sem comentários?" + +Não era suficiente que o professor e eu ambos sabíamos o que o programa deveria fazer. Parte do ponto da tarefa era me ensinar que meu código deve ser auto-explicativo para o próximo programador que viria depois de mim. Foi uma lição que eu não me esqueci. + +Comentários não são malignos. Eles são tão necessários para programação como as estruturas para ramificação ou de repetição. A maior parte das linguagens modernas tem uma ferramenta como o javadoc que irá processar comentários formatados apropriadamente e construir automaticamente um documento da API. Esse é um bom começo mas não suficiente. Dentro do seu código devem haver explicações sobre o código é esperado fazer. Codificar segundo um ditado antigo, "Se foi difícil para escrever, deve ser difícil para ler", faz um desserviço para seu cliente, seu empregador, seus colegas e até para você mesmo. + +Por outro lado, você pode ir bem longe com seus comentários. Certifique-se que seus comentários esclarecem seu código mas não tornem ele mais obscuro. Salpique seu código com comentários relevantes, explicando o que seu código é esperado fazer. Seus comentários de cabeçalho devem permitir a qualquer programador ter informação suficiente para usar seu código sem ter que lê-lo completamente, enquanto que os comentários de linha deve suportar o próximo programador a corrigir algum bug ou alterá-lo. + +Em um emprego que tive, eu discordei de uma decisão de design feita por aqueles acima de mim. Sentindo um tanto sarcástico, como jovens programadores geralmente se sentem, eu copiei o texto do e-mail que me instruía a usar o design proposto no comentário do cabeçalho daquele arquivo. Porém os gerentes nessa empresa em particular de fato revisaram o código que eu escrevi quando eu comitei o código. Foi minha primeira introdução ao termo "movimento limitante de carreira" + +Por [Cal Evans](http://programmer.97things.oreilly.com/wiki/index.php/Cal_Evans) \ No newline at end of file