Skip to content

Commit

Permalink
added thing_16 in pt_br
Browse files Browse the repository at this point in the history
  • Loading branch information
@disouzam
disouzam committed May 11, 2024
1 parent a57cf7d commit c9a251b
Show file tree
Hide file tree
Showing 2 changed files with 115 additions and 100 deletions.
200 changes: 100 additions & 100 deletions pt_br/SUMMARY.md
View file
Original file line number Diff line number Diff line change
@@ -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)
15 changes: 15 additions & 0 deletions pt_br/thing_16/README.md
View file
Original file line number Diff line number Diff line change
@@ -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)

0 comments on commit c9a251b

Please sign in to comment.