From a5f13a64cc3e0794dd324e90ee70281682f3058a Mon Sep 17 00:00:00 2001 From: Lauren Ferreira Date: Wed, 3 Jul 2019 20:37:40 -0300 Subject: [PATCH 1/8] =?UTF-8?q?Come=C3=A7o=20de=20tradu=C3=A7=C3=A3o=20da?= =?UTF-8?q?=20Motiva=C3=A7=C3=A3o?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- meta/why.md | 139 +++++++++++++++++++++++++++------------------------- 1 file changed, 71 insertions(+), 68 deletions(-) diff --git a/meta/why.md b/meta/why.md index f93e4e22..d066446a 100644 --- a/meta/why.md +++ b/meta/why.md @@ -1,79 +1,83 @@ -# Por que testes unitários e como fazê-los dar certo +# Por que criar testes unitários e como fazê-los dar certo -[Here's a link to a video of me chatting about this topic](https://www.youtube.com/watch?v=Kwtit8ZEK7U) +[Vejam um vídeo meu falando sobre esse assunto](https://www.youtube.com/watch?v=Kwtit8ZEK7U) -If you're not into videos, here's wordy version of it. +Se não gostar muito de vídeos, aqui vai o artigo relacionado a isso. ## Software -The promise of software is that it can change. This is why it is called _soft_ ware, it is malleable compared to hardware. A great engineering team should be an amazing asset to a company, writing systems that can evolve with a business to keep delivering value. +A promessa do software é que ele pode mudar. É por isso que é chamado de \_soft_ware: é mais maleável se comparado ao hardware. Uma boa equipe de engenharia deve ser um componente incrível para uma empresa, criando sistemas que podem evoluir com um negócio para manter seu valor de entrega. -So why are we so bad at it? How many projects do you hear about that outright fail? Or become "legacy" and have to be entirely re-written \(and the re-writes often fail too!\) +Então por que somos tão ruins nisso? Quantos projetos que você ouve falar sobre que ultrapassam o nível da falha? Ou viram "legado" e precisam ser totalmente recriados (e a reescrita também acaba falhando)! -How does a software system "fail" anyway? Can't it just be changed until it's correct? That's what we're promised! +Mas como é que um software "falha"? Não dá para ele apenas ser modificado até estar correto? É isso que prometemos! -A lot of people are choosing Go to build systems because it has made a number of choices which one hopes will make it more legacy-proof. +Muita gente costuma escolher o Go para criar sistemas porque a linguagem teve várias decisões que evitam que o software vire legado. -* Compared to my previous life of Scala where [I described how it has enough rope to hang yourself](http://www.quii.co.uk/Scala_-_Just_enough_rope_to_hang_yourself), Go has only 25 keywords and _a lot_ of systems can be built from the standard library and a few other small libraries. The hope is that with Go you can write code and come back to it in 6 months time and it'll still make sense. -* The tooling in respect to testing, benchmarking, linting & shipping is first class compared to most alternatives. -* The standard library is brilliant. -* Very fast compilation speed for tight feedback loops -* The Go backward compatibility promise. It looks like Go will get generics and other features in the future but the designers have promised that even Go code you wrote 5 years ago will still build. I literally spent weeks upgrading a project from Scala 2.8 to 2.10. +- Comparado à minha antiga vida de Scala onde [descrevi como é fácil acabar se dando mal com a linguagem](http://www.quii.co.uk/Scala_-_Just_enough_rope_to_hang_yourself), o Go tem apenas 25 palavras-chave. _Muitos_ sistemas podem ser criados a partir da biblioteca padrão e alguns outros pacotes pequenos. O que se espera é que com Go você possa escrever código, voltar a vê-lo 6 meses depois e ele ainda fazer sentido. +- As ferramentas relacionadas a testes, benchmarking, linting e shipping são incríveis se comparadas à maioria das alternativas. +- A biblioteca padrão é brilhante. +- Velocidade de compilação muito rápida para loops de feedback mais frequentes. +- A famigerada promessa da compatibilidade. Parece que Go vai receber `generics` e outras funcionalidades no futuro, mas os mantenedores prometeram que mesmo o código Go que você escreveram cinco anos atrás ainda vai compilar e funcionar. Eu literalmente passei semanas atualizando um projeto em Scala da versão 2.8 para a 2.10. -Even with all these great properties we can still make terrible systems, so we should look to the past and understand lessons in software engineering that apply no matter how shiny \(or not\) your language is. +Com todas essas propriedades ótimas, ainda podemos acabar criando sistemas terríveis. Por isso, precisamos aplicar lições de engenharia de software que se aplicam independente do quão maravilhosa (ou não) sua linguagem seja. -In 1974 a clever software engineer called \[Manny Lehman\]\([https://en.wikipedia.org/wiki/Manny\_Lehman\_\(computer\_scientist](https://en.wikipedia.org/wiki/Manny_Lehman_%28computer_scientist)\)\) wrote [Lehman's laws of software evolution](https://en.wikipedia.org/wiki/Lehman%27s_laws_of_software_evolution). +Em 1974, um engenheiro de software esperto chamado [Manny Lehman](https://pt.wikipedia.org/wiki/Meir_M._Lehman) escreveu as [leis de Lehman para a evolução do software](https://www.baguete.com.br/colunas/jorge-horacio-audy/17/04/2014/as-8-leis-de-lehman-foram-o-manifesto-do-seculo-xx). -> The laws describe a balance between forces driving new developments on one hand, and forces that slow down progress on the other hand. +> As leis descrevem um equilíbrio entre o desenvolvimento de software em uma ponta e a diminuição do progresso em outra. -These forces seem like important things to understand if we have any hope of not being in an endless cycle of shipping systems that turn into legacy and then get re-written over and over again. +É importante entender esses extremos para não acabar em um ciclo infinito de entregar sistemas que se tornam em legado e precisam ser reescritos novamente. -## The Law of Continuous Change +## Lei da Mudança Contínua -> Any software system used in the real-world must change or become less and less useful in the environment +> Qualquer software utilizado no mundo real precisa se adaptar ou vai se tornar cada vez mais obsoleto. -It feels obvious that a system _has_ to change or it becomes less useful but how often is this ignored? +Parece óbvio que um software _precisa_ mudar ou acaba se tornando menos útil, mas quantas vezes isso é ignorado? -Many teams are incentivised to deliver a project on a particular date and then moved on to the next project. If the software is "lucky" there is at least some kind of hand-off to another set of individuals to maintain it, but they didn't write it of course. +Muitas equipes são incentivadas a entregar um projeto em uma data específica e passar para o próximo projeto. Se o software tiver "sorte", vai acabar na mão de outro grupo de pessoas para mantê-lo, mas é claro que nenhuma dessas pessoas o escreveu. -People often concern themselves with trying to pick a framework which will help them "deliver quickly" but not focusing on the longevity of the system in terms of how it needs to evolve. +As pessoas se preocupam em escolher uma framework que vai ajudá-las a "entregar rapidamente", mas não focam na longevidade do sistema em termos de como precisa ser evoluído. -Even if you're an incredible software engineer, you will still fall victim to not knowing the future needs of your system. As the business changes some of the brilliant code you wrote is now no longer relevant. +Mesmo se você for um engenheiro de software incrível, ainda vai cair na armadilha de não saber que futuro aguarda seu software. Já que o negócio muda, o código brilhante que você escreveu já não vai mais ser relevante. -Lehman was on a roll in the 70s because he gave us another law to chew on. +Lehman estava contudo nos anos 70, porque nos deu outra lei para quebrarmos a cabeça. -## The Law of Increasing Complexity +## Lei da Complexidade Crescente -> As a system evolves, its complexity increases unless work is done to reduce it +> Enquanto o softwate evolui, sua complexidade aumenta. A não ser que um esforço seja investido para reduzi-la. -What he's saying here is we can't have software teams as blind feature factories, piling more and more features on to software in the hope it will survive in the long run. +O que ele diz aqui é que não podemos ter equipes de software para funcionar apenas como fábricas de funcionalidades, inserindo mais e mais funcionalidades no software para que ele possa sobreviver a longo prazo. -We **have** to keep managing the complexity of the system as the knowledge of our domain changes. +Nós **temos** que lidar com a complexidade do sistema conforme o conhecimento do nosso domínio muda. -## Refactoring +## Refatoração + +Existem _diversas_ facetas na engenharia de software que mantêm um software maleável, como: + +- There are _many_ facets of software engineering that keeps software malleable, such as: -* Developer empowerment -* Generally "good" code. Sensible separation of concerns, etc etc -* Communication skills -* Architecture -* Observability -* Deployability -* Automated tests -* Feedback loops +- Capacitação do desenvolvimento +- Em termos gerais, código "bom". Separação sensível de responsabilidades, etc +- Habilidades de comunicação +- Arquitetura +- Observabilidade +- Implantabilidade +- Testes automatizados +- Retornos de feedback -I am going to focus on refactoring. It's a phrase that gets thrown around a lot "we need to refactor this" - said to a developer on their first day of programming without a second thought. +Vou focar na refatoração. Quantas vezes você já ouviu a frase "precisamos refatorar isso"? Provavelmente dita para uma pessoa desenvolvedora em seu primeiro dia de programação sem pensar duas vezes. -Where does the phrase come from? How is refactoring just different from writing code? +De onde essa frase vem? Por que refatorar é diferente de escrever código? -I know that I and many others have _thought_ we were doing refactoring but we were mistaken +Sei que eu e muitas outras pessoas só _pensaram_ que estavam refatorando, mas estávamos cometendo um erro. -[Martin Fowler describes how people are getting it wrong](https://martinfowler.com/bliki/RefactoringMalapropism.html) +[Martin Fowler descreve como as pessoas entendem a refatoração errada aqui.](https://martinfowler.com/bliki/RefactoringMalapropism.html) -> However the term "refactoring" is often used when it's not appropriate. If somebody talks about a system being broken for a couple of days while they are refactoring, you can be pretty sure they are not refactoring. +> No entanto, o termo "refatoração" costuma ser utilizado de forma inapropriada. Se alguém fala que um sistema ficará quebrado por alguns dais enquanto está sendo refatorado, pode ter certeza que eles não estão refatorando. -So what is it? +Então o que é refatoração? ### Factorisation @@ -154,9 +158,9 @@ Those who choose not to write tests will typically be reliant on manual testing. **In order to safely refactor you need unit tests** because they provide -* Confidence you can reshape code without worrying about changing behaviour -* Documentation for humans as to how the system should behave -* Much faster and more reliable feedback than manual testing +- Confidence you can reshape code without worrying about changing behaviour +- Documentation for humans as to how the system should behave +- Much faster and more reliable feedback than manual testing #### An example in Go @@ -177,9 +181,9 @@ At the command line I can run `go test` and get immediate feedback as to whether You want to get in to a state where you are doing -* Small refactor -* Run tests -* Repeat +- Small refactor +- Run tests +- Repeat All within a very tight feedback loop so you don't go down rabbit holes and make mistakes. @@ -239,26 +243,26 @@ If you have these units that follow these properties you can write unit tests ag We've covered -* Refactoring -* Unit tests -* Unit design +- Refactoring +- Unit tests +- Unit design What we can start to see is that these facets of software design reinforce each other. ### Refactoring -* Gives us signals about our unit tests. If we have to do manual checks, we need more tests. If tests are wrongly failing then our tests are at the wrong abstraction level \(or have no value and should be deleted\). -* Helps us handle the complexities within and between our units. +- Gives us signals about our unit tests. If we have to do manual checks, we need more tests. If tests are wrongly failing then our tests are at the wrong abstraction level \(or have no value and should be deleted\). +- Helps us handle the complexities within and between our units. ### Unit tests -* Give a safety net to refactor. -* Verify and document the behaviour of our units. +- Give a safety net to refactor. +- Verify and document the behaviour of our units. ### \(Well designed\) units -* Easy to write _meaningful_ unit tests. -* Easy to refactor. +- Easy to write _meaningful_ unit tests. +- Easy to refactor. Is there a process to help us arrive at a point where we can constantly refactor our code to manage complexity and keep our systems malleable? @@ -276,11 +280,11 @@ TDD addresses the laws that Lehman talks about and other lessons hard learned th ### Small steps -* Write a small test for a small amount of desired behaviour -* Check the test fails with a clear error \(red\) -* Write the minimal amount of code to make the test pass \(green\) -* Refactor -* Repeat +- Write a small test for a small amount of desired behaviour +- Check the test fails with a clear error \(red\) +- Write the minimal amount of code to make the test pass \(green\) +- Refactor +- Repeat As you become proficient, this way of working will become natural and fast. @@ -290,9 +294,8 @@ You'll always be driving small & useful functionality comfortably backed by the ## Wrapping up -* The strength of software is that we can change it. _Most_ software will require change over time in unpredictable ways; but dont try and over-engineer because it's too hard to predict the future. -* Instead we need to make it so we can keep our software malleable. In order to change software we have to refactor it as it evolves or it will turn into a mess -* A good test suite can help you refactor quicker and in a less stressful manner -* Writing good unit tests is a design problem so think about structuring your code so you have meaningful units that you can integrate together like Lego bricks. -* TDD can help and force you to design well factored software iteratively, backed by tests to help future work as it arrives. - +- The strength of software is that we can change it. _Most_ software will require change over time in unpredictable ways; but dont try and over-engineer because it's too hard to predict the future. +- Instead we need to make it so we can keep our software malleable. In order to change software we have to refactor it as it evolves or it will turn into a mess +- A good test suite can help you refactor quicker and in a less stressful manner +- Writing good unit tests is a design problem so think about structuring your code so you have meaningful units that you can integrate together like Lego bricks. +- TDD can help and force you to design well factored software iteratively, backed by tests to help future work as it arrives. From 17be411c2d157d7f7e7159cbc2a12ac032e1537d Mon Sep 17 00:00:00 2001 From: Lauren Ferreira Date: Wed, 3 Jul 2019 22:45:02 -0300 Subject: [PATCH 2/8] Mais algumas leis --- meta/why.md | 146 ++++++++++++++++++++++++++-------------------------- 1 file changed, 72 insertions(+), 74 deletions(-) diff --git a/meta/why.md b/meta/why.md index d066446a..c248c81b 100644 --- a/meta/why.md +++ b/meta/why.md @@ -79,151 +79,149 @@ Sei que eu e muitas outras pessoas só _pensaram_ que estavam refatorando, mas e Então o que é refatoração? -### Factorisation +### Fatoração -When learning maths at school you probably learned about factorisation. Here's a very simple example +Quando estudava matemática na escola, você provavelmente aprendeu fatoração. Aqui vai um exemplo bem simples: -Calculate `1/2 + 1/4` +- Calcule `1/2 + 1/4` -To do this you _factorise_ the denominators, turning the expression into +Para fazer isso você `fatora` os denominadores (você também pode conhecer como MMC, mínimo múltiplo comum), transformando a expressão em `2/4 + 1/4` que então pode se transformar em `3/4`. -`2/4 + 1/4` which you can then turn into `3/4`. +Podemos tirar algumas lições importantes disso. Quando `fatoramos a expressão`, `não mudamos o que ela faz`. Ambas as expreções são iguais a `3/4`, mas facilitamos a forma como trabalhamos com esse resultado; trocar `1/2` por `2/4` torna nosso "domínio" mais fácil. -We can take some important lessons from this. When we _factorise the expression_ we have **not changed the meaning of the expression**. Both of them equal `3/4` but we have made it easier for us to work with; by changing `1/2` to `2/4` it fits into our "domain" easier. +Quando refatora seu código, você tenta encontrar formar de tornar seu código mais fácil de entender e "encaixar" no seu entendimento atual do que o sistema precisa fazer. Mas é extremamente importante que **o comportamento do código não seja alterado**. -When you refactor your code, you are trying to find ways of making your code easier to understand and "fit" into your current understanding of what the system needs to do. Crucially **you should not be changing behaviour**. +#### Exemplo em Go -#### An example in Go +Aqui está uma função que cumprimenta `nome` em uma `linguagem` específica: -Here is a function which greets `name` in a particular `language` +```go +func Ola(nome, linguagem string) string { -```text -func Hello(name, language string) string { - - if language == "es" { - return "Hola, " + name + if linguagem == "br" { + return "Olá, " + nome } - if language == "fr" { - return "Bonjour, " + name + if linguagem == "fr" { + return "Bonjour, " + nome } - // imagine dozens more languages + // e mais várias linguagens - return "Hello, " + name + return "Hello, " + nome } ``` -Having dozens of `if` statements doesn't feel good and we have a duplication of concatenating a language specific greeting with `,` and the `name.` So I'll refactor the code. +Não é bom ter várias condicionais `if` e temos uma duplicação que concatena um cumprimento específico da linguagem com `,` e o `nome`. Logo, vou refatorar o código. -```text -func Hello(name, language string) string { +```go +func Ola(nome, linguagem string) string { return fmt.Sprintf( "%s, %s", - greeting(language), - name, + cumprimento(linguagem), + nome, ) } -var greetings = map[string]string { - es: "Hola", +var cumprimentos = map[string]string { + br: "Olá", fr: "Bonjour", - //etc.. + // etc.. } -func greeting(language string) string { - greeting, exists := greetings[language] +func cumprimento(linguagem string) string { + cumprimento, existe := cumprimentos[linguagem] - if exists { - return greeting + if existe { + return cumprimento } return "Hello" } ``` -The nature of this refactor isn't actually important, what's important is I haven't changed behaviour. +A natureza dessa refatoração não é tão importante. O que importa é que não mudei o comportamento do código. -When refactoring you can do whatever you like, add interfaces, new types, functions, methods etc. The only rule is you don't change behaviour +Quando estiver refatorando, você pode fazer o que quiser: adicionar interfaces, tipos novos, funções, métodos etc. A única regra é que você não mude o comportamento do software. -### When refactoring code you must not be changing behaviour +### Quando estiver refatorando o código, seu comportamento não deve ser modificado -This is very important. If you are changing behaviour at the same time you are doing _two_ things at once. As software engineers we learn to break systems up into different files/packages/functions/etc because we know trying to understand a big blob of stuff is hard. +Isso é muito importante. Se estiver mudando o comportamento enquanto refatora, você vai estar fazendo _duas_ coisas de uma vez. Como engenheiros de software, aprendemos a dividir o sistema em diferentes arquivos/pacotes/funções/etc porque sabemos que tentar entender algo enorme e acoplado é difícil. -We don't want to have to be thinking about lots of things at once because that's when we make mistakes. I've witnessed so many refactoring endeavours fail because the developers are biting off more than they can chew. +Não queremos ter que pensar sobre muitas coisas ao mesmo tempo porque é aí que cometemos erros. Já vi tantos esforços de refatoração falharem pelas pessoas que estavam desenvolvendo darem um passo maior que a perna. -When I was doing factorisations in maths classes with pen and paper I would have to manually check that I hadn't changed the meaning of the expressions in my head. How do we know we aren't changing behaviour when refactoring when working with code, especially on a system that is non-trivial? +Quando fazia fatorações nas aulas de matemática com papel e caneta, eu precisava verificar manualmente que não havia mudado o significado das expressões na minha cabeça. Como sabemos que não estamos mudando o comportamento quando refatoramos as coisas no código, especialmente em um sistema que não é tão simples? -Those who choose not to write tests will typically be reliant on manual testing. For anything other than a small project this will be a tremendous time-sink and does not scale in the long run. +As pessoas que escolhem não escrever testes vão depender do teste manual. Para quem não trabalha em um projeto pequeno, isso vai ser uma tremenda perda de tempo e não vai escalar a longo prazo. -**In order to safely refactor you need unit tests** because they provide +**Para ter uma refatoração segura, você precisa escrever testes unitários**, porque eles te dão: -- Confidence you can reshape code without worrying about changing behaviour -- Documentation for humans as to how the system should behave -- Much faster and more reliable feedback than manual testing +- Confiança de que você pode mudar o código sem se preocupar com mudar seu comportamento +- Documentação para humanos sobre como o sistema deve se comportar +- Feedback mais rápido e confiável que o teste manual -#### An example in Go +#### Exemplo em Go -A unit test for our `Hello` function could look like this +Um teste unitário para a nossa função `Ola` pode ser feito assim: -```text -func TestHello(t *testing.T) { - got := Hello(“Chris”, es) - want := "Hola, Chris" +```go +func TestOla(t *testing.T) { + obtido := Ola(“Chris”, br) + esperado := "Olá, Chris" - if got != want { - t.Errorf("got '%s' want '%s'", got, want) + if obtido != esperado { + t.Errorf("obtido '%s' esperado '%s'", obtido, esperado) } } ``` -At the command line I can run `go test` and get immediate feedback as to whether my refactoring efforts have altered behaviour. In practice it's best to learn the magic button to run your tests within your editor/IDE. +Na linha de comando, posso executar `go test` e obter feedback imediato se minha refatoração alterou o comportamento da função. Na prática, é melhor aprender aonde fica o botão mágico que vai executar seus testes dentro do seu editor/IDE (ou rodar os testes sempre que salvar o arquivo). -You want to get in to a state where you are doing +Você deve entrar em uma rotina em que acaba fazendo: -- Small refactor -- Run tests -- Repeat +- Refatorar uma parte pequena +- Executar testes +- Repetir -All within a very tight feedback loop so you don't go down rabbit holes and make mistakes. +Tudo dentro de um ciclo de feedback contínuo para que você não caia em uma cilada e cometa erros. -Having a project where all your key behaviours are unit tested and give you feedback well under a second is a very empowering safety net to do bold refactoring when you need to. This helps us manage the incoming force of complexity that Lehman describes. +Ter um projeto onde os seus principais comportamentos são testados unicamente e te dão feedback em menos de um segundo traz uma relação forte de segurança para refatorar sempre que for necessário. Isso nos ajuda a gerenciar a complexidade crescente que Lehman descreve. -## If unit tests are so great, why is there sometimes resistance to writing them? +## Se testes unitários são tão bons, por que há resistência em escrevê-los? -On the one hand you have people \(like me\) saying that unit tests are important for the long term health of your system because they ensure you can keep refactoring with confidence. +De um lado, é possível ver pessoas (como eu) dizendo que testes unitários são importantes para a saúda do seu sistema a longo prazo, porque eles certificam que você possa continuar refatorando com confiança. -On the other you have people describing experiences of unit tests actually _hindering_ refactoring. +Do outro lado, é possível ver pessoas descrevendo experiências com testes unitários que na verdade _dificultaram_ a refatoração. -Ask yourself, how often do you have to change your tests when refactoring? Over the years I have been on many projects with very good test coverage and yet the engineers are reluctant to refactor because of the perceived effort of changing tests. +Se pergunte o seguinte: com qual frequência você precisa mudar seus testes quando refatora? Estive em diversos projetos com boa cobertura de testes e mesmo assim os engenheiros estavam relutantes em refatorar por causa do esforço perceptível de alterar testes. -This is the opposite of what we are promised! +Esse é o oposto do que prometemos! -### Why is this happening? +### Por que isso acontece? -Imagine you were asked to develop a square and we thought the best way to accomplish that would be stick two triangles together. +Imagine que te pediram para desenvolver um quadrado e você chegou à conclusão que seria necessário unir dois triângulos. -![Two right-angled triangles to form a square](https://i.imgur.com/ela7SVf.jpg) +![Dois triângulos retângulos formando um quadrado](https://i.imgur.com/ela7SVf.jpg) -We write our unit tests around our square to make sure the sides are equal and then we write some tests around our triangles. We want to make sure our triangles render correctly so we assert that the angles sum up to 180 degrees, perhaps check we make 2 of them, etc etc. Test coverage is really important and writing these tests is pretty easy so why not? +Escrevemos nossos testes unitários nos baseando no nosso quadrado para ter certeza de que os lados são iguais e depois escrevemos alguns testes em relação aos nossos triângulos. Queremos ter certeza de que nossos triângulos são renderizados corretamente, então afirmamos que os ângulos somados dos triângulos dão 180 graus, ou verificamos que os dois são criados, etc etc. A cobertura de testes é muito importante e escrever esses testes é bem fácil, então por que não? -A few weeks later The Law of Continuous Change strikes our system and a new developer makes some changes. She now believes it would be better if squares were formed with 2 rectangles instead of 2 triangles. +Algumas semanas depois, a Lei da Mudança Contínua bate no seu sistema e uma nova pessoa desenvolvedora faz algumas mudanças. Ela acredita que seria melhor se os quadrados fossem formados por dois retângulos ao invés dos dois triângulos. -![Two rectangles to form a square](https://i.imgur.com/1G6rYqD.jpg) +![Dois retângulos formando um quadrado](https://i.imgur.com/1G6rYqD.jpg) -She tries to do this refactor and gets mixed signals from a number of failing tests. Has she actually broken important behaviours here? She now has to dig through these triangle tests and try and understand what's going on. +Ela tenta fazer essa refatoração e percebe que alguns testes falharam. Ela quebrou algum comportamento realmente importante aqui? Agora ela tem que investigar esses testes de triângulo e entender o que está acontecendo. -_It's not actually important that the square was formed out of triangles_ but **our tests have falsely elevated the importance of our implementation details**. +_Na verdade, não é tão importante que o quadrado seja formado por triângulo_, mas **nossos testes fizeram com que isso parecesse mais importante do que deveria em relação aos detalhes da nossa implementação** -## Favour testing behaviour rather than implementation detail +## Favorecer o comportamento do teste ao invés do detalhe da implementação -When I hear people complaining about unit tests it is often because the tests are at the wrong abstraction level. They're testing implementation details, overly spying on collaborators and mocking too much. +Quando ouço pessoas reclamando sobre testes unitários, frequentemente o motivo é que eles estão em um nível errado de abstração. Eles testam detalhes da implementação, testando coisas muito específicas ou fazendo muitos mocks. -I believe it stems from a misunderstanding of what unit tests are and chasing vanity metrics \(test coverage\). +Acredito que isso deriva de uma falta de entendimento do que testes unitários são e perseguem métricas vaidosas (cobertura de testes). -If I am saying just test behaviour, should we not just only write system/black-box tests? These kind of tests do have lots of value in terms of verifying key user journeys but they are typically expensive to write and slow to run. For that reason they're not too helpful for _refactoring_ because the feedback loop is slow. In addition black box tests don't tend to help you very much with root causes compared to unit tests. +Se estou apenas testando o comportamento, não deveríamos apenas escrever testes de sistema/caixa preta? Esses tipos de testes geram muito valor em termos de verificar as principais jornadas do usuário, mas costumam ser difíceis de escrever e lentos para rodar. Por esse motivos, eles não são muito úteis para a _refatoração_ porque o ciclo de feedback é lento. Além disso, os testes de caixa preta tendem a não te ajudar muito com as causas de origem comparados aos testes unitários. -So what _is_ the right abstraction level? +Logo, _qual_ é o nível de abstração correto? ## Writing effective unit tests is a design problem From 62f124153e53783482d97c4098b3d9859f699d70 Mon Sep 17 00:00:00 2001 From: Lauren Ferreira Date: Thu, 4 Jul 2019 20:18:12 -0300 Subject: [PATCH 3/8] =?UTF-8?q?Tradu=C3=A7=C3=A3o=20de=20Motiva=C3=A7?= =?UTF-8?q?=C3=A3o?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- meta/why.md | 88 ++++++++++++++++++++++++++--------------------------- 1 file changed, 44 insertions(+), 44 deletions(-) diff --git a/meta/why.md b/meta/why.md index c248c81b..b12be655 100644 --- a/meta/why.md +++ b/meta/why.md @@ -223,77 +223,77 @@ Se estou apenas testando o comportamento, não deveríamos apenas escrever teste Logo, _qual_ é o nível de abstração correto? -## Writing effective unit tests is a design problem +## Escrevendo testes unitários de forma efetiva é um problema de design -Forgetting about tests for a moment, it is desirable to have within your system self-contained, decoupled "units" centered around key concepts in your domain. +Deixando testes de lado por um momento, é desejável "unidades" independentes e desacopladas dentro do seu sistema, centradas em torno de conceitos essenciais do seu domínio. -I like to imagine these units as simple Lego bricks which have coherent APIs that I can combine with other bricks to make bigger systems. Underneath these APIs there could be dozens of things \(types, functions et al\) collaborating to make them work how they need to. +Gosto de imaginar essas unidades tão simples quanto blocos de Lego que têm APIs coerentes e que eu possa combinar com outros blocos para criar sistemas maiores. Por baixo dessas APIs pode haver várisas coisas (tipos, funções etc) colaborando para fazê-las funcionar conforme esperado. -For instance if you were writing a bank in Go, you might have an "account" package. It will present an API that does not leak implementation detail and is easy to integrate with. +Por exemplo: se estiver escrevendo um banco em Go, você deve ter um pacote "conta". Ele vai te apresentar uma API que não vaza detalhes da implementação e é fácil de ser integrado. -If you have these units that follow these properties you can write unit tests against their public APIs. _By definition_ these tests can only be testing useful behaviour. Underneath these units I am free to refactor the implementation as much as I need to and the tests for the most part should not get in the way. +Se tiver essas unidades que seguem essas propriedades, você consegue escrever testes unitários para suas APIs públicas. _Por definição_, esses testes só podem testar os comportamentos importantes. Por baixo dos panos dessas unidades, fico livre para refatorar a implementação o quanto eu precisar e os testes para a maior parte dela não deve me atrapalhar. -### Are these unit tests? +### Mas são testes unitários, mesmo? -**YES**. Unit tests are against "units" like I described. They were _never_ about only being against a single class/function/whatever. +**SIM**. Testes unitários são feitos para "unidades", como já descrevi. Eles _nunca_ devem ser feitos para uma classe/função/seja lá o que for. -## Bringing these concepts together +## Conclusão -We've covered +Falamos sobre -- Refactoring -- Unit tests -- Unit design +- Refatoração +- Testes unitários +- Desenvolvimento de unidade -What we can start to see is that these facets of software design reinforce each other. +O que podemos começar a ver é que essas facetas do desenvolvimento de software reforçam uma à outra. -### Refactoring +### Refatoração -- Gives us signals about our unit tests. If we have to do manual checks, we need more tests. If tests are wrongly failing then our tests are at the wrong abstraction level \(or have no value and should be deleted\). -- Helps us handle the complexities within and between our units. +- Nos dá sinais sobre nossos testes unitários. Se precisamos fazer validações manuais, precisamos de mais testes. Se testes estão falhando incorretamente, então nossos testes estão no nível errado de abstração (ou não têm valor e precisam ser deletados). +- Nos ajuda a lidar com as complexidades dentro e entre nossas unidades. -### Unit tests +### Testes unitários -- Give a safety net to refactor. -- Verify and document the behaviour of our units. +- Nos dá a garantia para refatoração. +- Verificam e documentam o comportamento de nossas unidades. -### \(Well designed\) units +### Unidades (bem definidas) -- Easy to write _meaningful_ unit tests. -- Easy to refactor. +- Facilitam a escrita de testes unitários _significativos_. +- Facilitam a refatoração. -Is there a process to help us arrive at a point where we can constantly refactor our code to manage complexity and keep our systems malleable? +Há um processo que nos ajuda a alcançar um ponto onde podemos refatorar nosso código para lidaar com a complexidade e manter nossos sistemas maleáveis? -## Why Test Driven Development \(TDD\) +## Por que Desenvolvimento Orientado a Testes (TDD) -Some people might take Lehman's quotes about how software has to change and overthink elaborate designs, wasting lots of time upfront trying to create the "perfect" extensible system and end up getting it wrong and going nowhere. +Algumas pessoas levam as citações de Lehman sobre como o software deve mudar a sério demais e elaboram sistemas complexos demais, gastando muito tempo tentando prever o impossível para criar o sistema extensível "perfeito" e acabam entendendo da forma errada e chegando a lugar nenhum. -This is the bad old days of software where an analyst team would spend 6 months writing a requirements document and an architect team would spend another 6 months coming up with a design and a few years later the whole project fails. +Isso vem da época das trevas do software onde um time de analistas costumava perder seis meses escrevendo um documento de requerimentos e a equipe de arquitetura perdia outros seis meses para desenvolvê-lo e alguns anos depois o projeto inteiro falhava. -I say bad old days but this still happens! +Eu disse que era uma época das trevas, mas isso ainda acontece! -Agile teaches us that we need to work iteratively, starting small and evolving the software so that we get fast feedback on the design of our software and how it works with real users; TDD enforces this approach. +O movimento ágil nos ensina que precisamos trabalhar de forma iterativa, começando com pouca coisa e evoluindo o software para que tenhamos retorno rápido do design do nosso software e como ele trabalha com usuários reais; o TDD reforça essa abordagem. -TDD addresses the laws that Lehman talks about and other lessons hard learned through history by encouraging a methodology of constantly refactoring and delivering iteratively. +O TDD aborda as leis que Lehman fala sobre e outras lições difíceis aprendidas no decorrer da história encorajando uma metodologia de refatoração constante e entrega contínua. -### Small steps +### Etapas pequenas -- Write a small test for a small amount of desired behaviour -- Check the test fails with a clear error \(red\) -- Write the minimal amount of code to make the test pass \(green\) -- Refactor -- Repeat +- Escrever um teste pequeno para uma unidade do comportamento desejado +- Verificar que o teste falha com um erro claro (vermelho) +- Escrever o mínimo de código para fazer o teste passar (verde) +- Refatorar +- Repetir -As you become proficient, this way of working will become natural and fast. +Conforme você pratica, essa mentalidade vai se tornar natural e rápida. -You'll come to expect this feedback loop to not take very long and feel uneasy if you're in a state where the system isn't "green" because it indicates you may be down a rabbit hole. +Você vai esperar que esse ciclo de feedback não leve muito tempo e se sentir desconfortável se estiver em um estado em que seu sistema não está "verde" por isso poder indicar que você pode ter deixado algo passar. -You'll always be driving small & useful functionality comfortably backed by the feedback from your tests. +Você sempre vai desenvolver de forma a criar funcionalidades pequenas & úteis confortavelmente reforçadas pelo feedback dos seus testes. -## Wrapping up +## Resumindo -- The strength of software is that we can change it. _Most_ software will require change over time in unpredictable ways; but dont try and over-engineer because it's too hard to predict the future. -- Instead we need to make it so we can keep our software malleable. In order to change software we have to refactor it as it evolves or it will turn into a mess -- A good test suite can help you refactor quicker and in a less stressful manner -- Writing good unit tests is a design problem so think about structuring your code so you have meaningful units that you can integrate together like Lego bricks. -- TDD can help and force you to design well factored software iteratively, backed by tests to help future work as it arrives. +- O ponto forte do software é que podemos mudá-lo. A _maioria_ dos software requer mudança com o tempo de formas imprevisíveis; não tente pensar muito à frente porque é difícil prever o futuro. +- Ao invés disso, precisamos criar nosso software de forma que ele possa se manter maleável. Para mudar o software precisamos refatorá-lo conforme ele evolui, ou vai acabar virando uma bagunça. +- Um bom conjunto de testes pode te ajudar a refatorar mais rápido e de forma menos estressante. +- Escrever bons testes unitários é um problema de design. Logo, pense em estruturar seu código de forma que ele tenha unidades significativas que possam ser unidas como blocos de Lego. +- O TDD pode ajudar e te forçar a desenvolver softwares bem fatorados continuamente, reforçados por testes para te ajudar com futuros trabalhos que podem chegar. From 847b3ca281be0ec178d90da1521ae19bcf016172 Mon Sep 17 00:00:00 2001 From: Lauren Ferreira Date: Thu, 4 Jul 2019 20:20:03 -0300 Subject: [PATCH 4/8] =?UTF-8?q?Troca=20de=20why.md=20para=20motivacao.md?= =?UTF-8?q?=20e=20formata=C3=A7=C3=A3o?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 67 +++++++++++++++++------------------ SUMMARY.md | 61 ++++++++++++++++--------------- build.books.sh | 4 +-- gb-readme.md | 43 +++++++++++----------- meta/{why.md => motivacao.md} | 0 5 files changed, 86 insertions(+), 89 deletions(-) rename meta/{why.md => motivacao.md} (100%) diff --git a/README.md b/README.md index 8097a10c..6b8016cf 100644 --- a/README.md +++ b/README.md @@ -6,16 +6,16 @@ ![Build Status](https://travis-ci.org/larien/learn-go-with-tests.svg?branch=master) [![Go Report Card](https://goreportcard.com/badge/github.com/larien/learn-go-with-tests)](https://goreportcard.com/report/github.com/quii/learn-go-with-tests) -* Formatos: [Gitbook](https://larien.gitbook.io/aprenda-go-com-testes), [EPUB or PDF](https://github.com/larien/learn-go-with-tests/releases) -* Versão original: [English](https://quii.gitbook.io/learn-go-with-tests/) -* Traduções: [中文](https://studygolang.gitbook.io/learn-go-with-tests) +- Formatos: [Gitbook](https://larien.gitbook.io/aprenda-go-com-testes), [EPUB or PDF](https://github.com/larien/learn-go-with-tests/releases) +- Versão original: [English](https://quii.gitbook.io/learn-go-with-tests/) +- Traduções: [中文](https://studygolang.gitbook.io/learn-go-with-tests) ## Motivação -* Explore a linguagem Go escrevendo testes -* **Tenha uma base com TDD**. O Go é uma boa linguagem para aprender TDD por ser simples de aprender e ter testes nativamente -* Tenha confiança de que você será capaz de escrever sistemas robustos e bem testados em Go -* [Assista a um vídeo ou leia sobre o motivo pelo qual testes unitários e TDD são importantes](meta/why.md) +- Explore a linguagem Go escrevendo testes +- **Tenha uma base com TDD**. O Go é uma boa linguagem para aprender TDD por ser simples de aprender e ter testes nativamente +- Tenha confiança de que você será capaz de escrever sistemas robustos e bem testados em Go +- [Assista a um vídeo ou leia sobre o motivo pelo qual testes unitários e TDD são importantes](meta/motivacao.md) ## Índice @@ -49,12 +49,12 @@ Novos conceitos serão apresentados para ajudar a escrever código de qualidade, No final desse capítulo, você deverá ter uma boa ideia de como escrever uma aplicação em Go testada. -* [Servidor HTTP](criando-uma-aplicacao/http-server.md) - Vamos criar uma aplicação que espera por requisições HTTP e as responde. -* [JSON, routing e embedding](criando-uma-aplicacao/json.md) - Vamos fazer nossos endpoints retornarem JSON e explorar como trabalhar com rotas. -* [IO e classificação](criando-uma-aplicacao/io.md) - Vamos persistir e ler nossos dados do disco e falar sobre classificação de dados. -* [Linha de comando e estrutura do projeto](criando-uma-aplicacao/command-line.md) - Suportar diversas aplicações em uma base de código e ler entradas da linha de comando. -* [Tempo](criando-uma-aplicacao/time.md) - Usar o pacote `time` para programar atividades. -* [Websockets](criando-uma-aplicacao/websockets.md) - Aprender a escrever e testar um servidor que usa websockets. +- [Servidor HTTP](criando-uma-aplicacao/http-server.md) - Vamos criar uma aplicação que espera por requisições HTTP e as responde. +- [JSON, routing e embedding](criando-uma-aplicacao/json.md) - Vamos fazer nossos endpoints retornarem JSON e explorar como trabalhar com rotas. +- [IO e classificação](criando-uma-aplicacao/io.md) - Vamos persistir e ler nossos dados do disco e falar sobre classificação de dados. +- [Linha de comando e estrutura do projeto](criando-uma-aplicacao/command-line.md) - Suportar diversas aplicações em uma base de código e ler entradas da linha de comando. +- [Tempo](criando-uma-aplicacao/time.md) - Usar o pacote `time` para programar atividades. +- [Websockets](criando-uma-aplicacao/websockets.md) - Aprender a escrever e testar um servidor que usa websockets. ### Dúvidas e respostas @@ -64,15 +64,15 @@ Costumo ver perguntas nas Interwebs como: Se tiver esse tipo de dúvida, crie uma Issue no GitHub e vou tentar achar tempo para escrever um pequeno capítulo para resolver o problema. Acho que conteúdo como esse é valioso, já que está resolvendo problemas `reais` envolvendo testes que as pessoas têm. -* [OS exec](perguntas-e-respostas/os-exec.md) - Um exemplo de como podemos usar o sistema operacional para executar comandos para buscar dados e manter nossa lógica de negócio testável. -* [Tipos de erro](perguntas-e-respostas/error-types.md) - Exemplo de como criar seus próprios tipos de erro para melhorar seus testes e tornar seu código mais fácil de se trabalhar. +- [OS exec](perguntas-e-respostas/os-exec.md) - Um exemplo de como podemos usar o sistema operacional para executar comandos para buscar dados e manter nossa lógica de negócio testável. +- [Tipos de erro](perguntas-e-respostas/error-types.md) - Exemplo de como criar seus próprios tipos de erro para melhorar seus testes e tornar seu código mais fácil de se trabalhar. ## Contribuição -* _Esse projeto está em desenvolvimento_, tanto seu conteúdo original quanto sua tradução. Se tiver interesse em contribuir, por favor entre em contato. -* Leia [contributing.md](meta/contributing.md) para algumas diretrizes. -* Quer ajudar com a tradução para o português? Leia [translating.md](meta/translating.md) e entenda como o processo de tradução está organizado. -* Tem ideias? Crie uma issue! +- _Esse projeto está em desenvolvimento_, tanto seu conteúdo original quanto sua tradução. Se tiver interesse em contribuir, por favor entre em contato. +- Leia [contributing.md](meta/contributing.md) para algumas diretrizes. +- Quer ajudar com a tradução para o português? Leia [translating.md](meta/translating.md) e entenda como o processo de tradução está organizado. +- Tem ideias? Crie uma issue! ## Explicação @@ -116,41 +116,40 @@ Usando minha experiência de aprendizado em grupo e a minha própria, vou tentar ## Para quem isso foi feito -* Pessoas que se interessam em aprender Go. -* Pessoas que já sabem Go, mas querem explorar testes com TDD. +- Pessoas que se interessam em aprender Go. +- Pessoas que já sabem Go, mas querem explorar testes com TDD. ## O que vamos precisar -* Um computador! -* [Go instalado](https://golang.org/) -* Um editor de texto -* Experiência com programação. Entendimento de conceitos como `if`, variáveis, funções etc. -* Se sentir confortável com o terminal +- Um computador! +- [Go instalado](https://golang.org/) +- Um editor de texto +- Experiência com programação. Entendimento de conceitos como `if`, variáveis, funções etc. +- Se sentir confortável com o terminal -## Traduzido com :blue\_heart: por +## Traduzido com :blue_heart: por -* [Diego Nascimento](https://github.com/diegonvs) +- [Diego Nascimento](https://github.com/diegonvs) [twitter](https://twitter.com/diegonvs97) [linkedin](https://www.linkedin.com/in/dnvs97/) -* [Jéssica Paz](https://github.com/jessicapaz) +- [Jéssica Paz](https://github.com/jessicapaz) [site](https://jessicapaz.me) [twitter](https://twitter.com/jessicamorim42) [linkedin](https://www.linkedin.com/in/jessica-paz/) -* [Lauren Ferreira](https://github.com/larien) +- [Lauren Ferreira](https://github.com/larien) [site](https://larien.dev) [twitter](https://twitter.com/larienmf) [linkedin](https://www.linkedin.com/in/lauren-ferreira/) -* [Rafael Acioly](https://github.com/rafa-acioly) +- [Rafael Acioly](https://github.com/rafa-acioly) [twitter](https://twitter.com/R_acioly) [linkedin](https://www.linkedin.com/in/rafaelacioly/) ## Feedback -* Crie issues/submita PRs [aqui](https://github.com/quii/learn-go-with-tests) ou [me envie um tweet em @quii](https://twitter.com/quii). -* Para a versão em português, submita um PR [aqui](https://github.com/larien/learn-go-with-tests) ou entre em contato comigo pelo [meu site](https://larien.dev). +- Crie issues/submita PRs [aqui](https://github.com/quii/learn-go-with-tests) ou [me envie um tweet em @quii](https://twitter.com/quii). +- Para a versão em português, submita um PR [aqui](https://github.com/larien/learn-go-with-tests) ou entre em contato comigo pelo [meu site](https://larien.dev). [MIT license](https://github.com/larien/learn-go-with-tests/tree/09aafaeebaef4443e80a6216cc46fa3d7bfdabbb/LICENSE.md) [Logo criado por egonelbre](https://github.com/egonelbre) Que estrela! - diff --git a/SUMMARY.md b/SUMMARY.md index c0064ab3..947f4e6b 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,45 +1,44 @@ # Table of contents -* [Introdução](README.md) -* [Aprenda Go com Testes](gb-readme.md) +- [Introdução](README.md) +- [Aprenda Go com Testes](gb-readme.md) ## Primeiros Passos com Go -* [Instalação do Go](primeiros-passos-com-go/install-go.md) -* [Olá, mundo](primeiros-passos-com-go/hello-world.md) -* [Inteiros](primeiros-passos-com-go/integers.md) -* [Iteração](primeiros-passos-com-go/iteration.md) -* [Arrays e slices](primeiros-passos-com-go/arrays-and-slices.md) -* [Estruturas, métodos e interfaces](primeiros-passos-com-go/structs-methods-and-interfaces.md) -* [Ponteiros e erros](primeiros-passos-com-go/pointers-and-errors.md) -* [Maps](primeiros-passos-com-go/maps.md) -* [Injeção de dependência](primeiros-passos-com-go/dependency-injection.md) -* [Mocking](primeiros-passos-com-go/mocking.md) -* [Concorrência](primeiros-passos-com-go/concurrency.md) -* [Select](primeiros-passos-com-go/select.md) -* [Reflection](primeiros-passos-com-go/reflection.md) -* [Sync](primeiros-passos-com-go/sync.md) -* [Context](primeiros-passos-com-go/context.md) +- [Instalação do Go](primeiros-passos-com-go/install-go.md) +- [Olá, mundo](primeiros-passos-com-go/hello-world.md) +- [Inteiros](primeiros-passos-com-go/integers.md) +- [Iteração](primeiros-passos-com-go/iteration.md) +- [Arrays e slices](primeiros-passos-com-go/arrays-and-slices.md) +- [Estruturas, métodos e interfaces](primeiros-passos-com-go/structs-methods-and-interfaces.md) +- [Ponteiros e erros](primeiros-passos-com-go/pointers-and-errors.md) +- [Maps](primeiros-passos-com-go/maps.md) +- [Injeção de dependência](primeiros-passos-com-go/dependency-injection.md) +- [Mocking](primeiros-passos-com-go/mocking.md) +- [Concorrência](primeiros-passos-com-go/concurrency.md) +- [Select](primeiros-passos-com-go/select.md) +- [Reflection](primeiros-passos-com-go/reflection.md) +- [Sync](primeiros-passos-com-go/sync.md) +- [Context](primeiros-passos-com-go/context.md) ## Criando uma aplicação -* [Introdução](criando-uma-aplicacao/app-intro.md) -* [Servidor HTTP](criando-uma-aplicacao/http-server.md) -* [JSON, roteamento and embedding](criando-uma-aplicacao/json.md) -* [IO e sorting](criando-uma-aplicacao/io.md) -* [Linha de comando e estrutura de pacotes](criando-uma-aplicacao/command-line.md) -* [Tempo](criando-uma-aplicacao/time.md) -* [Websockets](criando-uma-aplicacao/websockets.md) +- [Introdução](criando-uma-aplicacao/app-intro.md) +- [Servidor HTTP](criando-uma-aplicacao/http-server.md) +- [JSON, roteamento and embedding](criando-uma-aplicacao/json.md) +- [IO e sorting](criando-uma-aplicacao/io.md) +- [Linha de comando e estrutura de pacotes](criando-uma-aplicacao/command-line.md) +- [Tempo](criando-uma-aplicacao/time.md) +- [Websockets](criando-uma-aplicacao/websockets.md) ## Perguntas e respostas -* [OS Exec](perguntas-e-respostas/os-exec.md) -* [Tipos de erro](perguntas-e-respostas/error-types.md) +- [OS Exec](perguntas-e-respostas/os-exec.md) +- [Tipos de erro](perguntas-e-respostas/error-types.md) ## Meta -* [Por que testes unitários e como fazê-los dar certo](meta/why.md) -* [Como contribuir](meta/contributing.md) -* [Como traduzir](meta/translating.md) -* [Template de capítulo](meta/template.md) - +- [Por que testes unitários e como fazê-los dar certo](meta/motivacao.md) +- [Como contribuir](meta/contributing.md) +- [Como traduzir](meta/translating.md) +- [Template de capítulo](meta/template.md) diff --git a/build.books.sh b/build.books.sh index 2cb9f10b..a245c3c3 100755 --- a/build.books.sh +++ b/build.books.sh @@ -4,7 +4,7 @@ set -e docker run -v `pwd`:/source jagregory/pandoc -o aprenda-go-com-testes.pdf --latex-engine=xelatex --variable urlcolor=blue --toc --toc-depth=1 pdf-cover.md \ gb-readme.md \ - meta/why.md \ + meta/motivacao.md \ primeiros-passos-com-go/hello-world.md \ primeiros-passos-com-go/integers.md \ primeiros-passos-com-go/arrays-and-slices.md \ @@ -30,7 +30,7 @@ docker run -v `pwd`:/source jagregory/pandoc -o aprenda-go-com-testes.pdf --late docker run -v `pwd`:/source jagregory/pandoc -o aprenda-go-com-testes.epub --latex-engine=xelatex --toc --toc-depth=1 title.txt \ gb-readme.md \ - meta/why.md \ + meta/motivacao.md \ primeiros-passos-com-go/hello-world.md \ primeiros-passos-com-go/integers.md \ primeiros-passos-com-go/arrays-and-slices.md \ diff --git a/gb-readme.md b/gb-readme.md index 3fce931f..5243b297 100644 --- a/gb-readme.md +++ b/gb-readme.md @@ -4,16 +4,16 @@ [Arte por Denise](https://twitter.com/deniseyu21) -* Formatos: [Gitbook](https://larien.gitbook.io/aprenda-go-com-testes), [EPUB or PDF](https://github.com/larien/learn-go-with-tests/releases) -* Versão original: [English](https://quii.gitbook.io/learn-go-with-tests/) -* Traduções: [Chinese](https://studygolang.gitbook.io/learn-go-with-tests) +- Formatos: [Gitbook](https://larien.gitbook.io/aprenda-go-com-testes), [EPUB or PDF](https://github.com/larien/learn-go-with-tests/releases) +- Versão original: [English](https://quii.gitbook.io/learn-go-with-tests/) +- Traduções: [Chinese](https://studygolang.gitbook.io/learn-go-with-tests) ## Motivação -* Explore a linguagem Go escrevendo testes -* **Tenha uma base com TDD**. O Go é uma boa linguagem para aprender TDD por ser simples de aprender e ter testes nativamente -* Tenha confiança de que você será capaz de escrever sistemas robustos e bem testados em Go -* [Assista a um vídeo ou leia sobre o motivo pelo qual testes unitários e TDD são importantes](meta/why.md) +- Explore a linguagem Go escrevendo testes +- **Tenha uma base com TDD**. O Go é uma boa linguagem para aprender TDD por ser simples de aprender e ter testes nativamente +- Tenha confiança de que você será capaz de escrever sistemas robustos e bem testados em Go +- [Assista a um vídeo ou leia sobre o motivo pelo qual testes unitários e TDD são importantes](meta/motivacao.md) ## Explicação @@ -57,41 +57,40 @@ Usando minha experiência de aprendizado em grupo e a minha própria, vou tentar ## Para quem isso foi feito -* Pessoas que se interessam em aprender Go. -* Pessoas que já sabem Go, mas querem explorar testes com TDD. +- Pessoas que se interessam em aprender Go. +- Pessoas que já sabem Go, mas querem explorar testes com TDD. ## O que vamos precisar -* Um computador! -* [Go instalado](https://golang.org/) -* Um editor de texto -* Experiência com programação. Entendimento de conceitos como `if`, variáveis, funções etc. -* Se sentir confortável com o terminal +- Um computador! +- [Go instalado](https://golang.org/) +- Um editor de texto +- Experiência com programação. Entendimento de conceitos como `if`, variáveis, funções etc. +- Se sentir confortável com o terminal ## Feedback -* Crie issues/submita PRs [aqui](https://github.com/quii/learn-go-with-tests) ou [me envie um tweet em @quii](https://twitter.com/quii). -* Para a versão em português, submita um PR [aqui](https://github.com/larien/learn-go-with-tests) ou entre em contato comigo pelo [meu site](https://larien.dev). +- Crie issues/submita PRs [aqui](https://github.com/quii/learn-go-with-tests) ou [me envie um tweet em @quii](https://twitter.com/quii). +- Para a versão em português, submita um PR [aqui](https://github.com/larien/learn-go-with-tests) ou entre em contato comigo pelo [meu site](https://larien.dev). [MIT license](https://github.com/larien/learn-go-with-tests/tree/35d0dbb8c6467128a4b4637742b4c2fe563c0a88/LICENSE.md) [Logo criado por egonelbre](https://github.com/egonelbre) Que estrela! -## Traduzido com :blue\_heart: por +## Traduzido com :blue_heart: por -* [Diego Nascimento](https://github.com/diegonvs) +- [Diego Nascimento](https://github.com/diegonvs) [twitter](https://twitter.com/diegonvs97) [linkedin](https://www.linkedin.com/in/dnvs97/) -* [Jéssica Paz](https://github.com/jessicapaz) +- [Jéssica Paz](https://github.com/jessicapaz) [site](https://jessicapaz.me) [twitter](https://twitter.com/jessicamorim42) [linkedin](https://www.linkedin.com/in/jessica-paz/) -* [Lauren Ferreira](https://github.com/larien) +- [Lauren Ferreira](https://github.com/larien) [site](https://larien.dev) [twitter](https://twitter.com/larienmf) [linkedin](https://www.linkedin.com/in/lauren-ferreira/) -* [Rafael Acioly](https://github.com/rafa-acioly) +- [Rafael Acioly](https://github.com/rafa-acioly) [twitter](https://twitter.com/R_acioly) [linkedin](https://www.linkedin.com/in/rafaelacioly/) - diff --git a/meta/why.md b/meta/motivacao.md similarity index 100% rename from meta/why.md rename to meta/motivacao.md From 333d382b2c501309308b4b39550bb74834fa032b Mon Sep 17 00:00:00 2001 From: Lauren Ferreira Date: Thu, 4 Jul 2019 20:40:06 -0300 Subject: [PATCH 5/8] Troca de template.md para exemplo.md --- SUMMARY.md | 2 +- meta/contributing.md | 35 +++++++++++++++++------------------ meta/exemplo.md | 17 +++++++++++++++++ meta/template.md | 18 ------------------ 4 files changed, 35 insertions(+), 37 deletions(-) create mode 100644 meta/exemplo.md delete mode 100644 meta/template.md diff --git a/SUMMARY.md b/SUMMARY.md index 947f4e6b..3eeb8cb0 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -41,4 +41,4 @@ - [Por que testes unitários e como fazê-los dar certo](meta/motivacao.md) - [Como contribuir](meta/contributing.md) - [Como traduzir](meta/translating.md) -- [Template de capítulo](meta/template.md) +- [Exemplo de capítulo](meta/exemplo.md) diff --git a/meta/contributing.md b/meta/contributing.md index fe2600d4..d1c44aea 100644 --- a/meta/contributing.md +++ b/meta/contributing.md @@ -4,26 +4,25 @@ Contributions are very welcome. I hope for this to become a great home for guide ## What we're looking for -* Teaching Go features \(e.g things like `if`, `select`, structs, methods, etc\). -* Showcase interesting functionality within the standard library. Show off how easy it is to TDD a HTTP server for instance. -* Show how Go's tooling, like benchmarking, race detectors, etc can help you arrive at great software. +- Teaching Go features \(e.g things like `if`, `select`, structs, methods, etc\). +- Showcase interesting functionality within the standard library. Show off how easy it is to TDD a HTTP server for instance. +- Show how Go's tooling, like benchmarking, race detectors, etc can help you arrive at great software. If you don't feel confident to submit your own guide, submitting an issue for something you want to learn is still a valuable contribution. ## Style guide -* Always be reinforcing the TDD cycle. Take a look at the [Chapter Template](template.md). -* Emphasis on iterating over functionality driven by tests. The Hello, world example works well because we gradually make it more sophisticated and learning new techniques _driven_ by the tests. For example: - * `Hello()` <- how to write functions, return types. - * `Hello(name string)` <- arguments, constants. - * `Hello(name string)` <- default to "world" using `if`. - * `Hello(name, language string)` <- `switch`. -* Try and minimise the surface area of required knowledge. - * Thinking of examples that showcase what you're trying to teach without confusing the reader with other features is important. - * For example you can learn about `struct`s without understanding pointers. - * Brevity is king. -* Follow the [Code Review Comments style guide](https://github.com/golang/go/wiki/CodeReviewComments). It's important for a consistent style across all the sections. -* Your section should have a runnable application at the end \(e.g `package main` with a `main` func\) so users can see it in action and play with it. -* All tests should pass. -* Run `./build.sh` before raising PR. - +- Always be reinforcing the TDD cycle. Take a look at the [exemplo de capítulo](exemplo.md). +- Emphasis on iterating over functionality driven by tests. The Hello, world example works well because we gradually make it more sophisticated and learning new techniques _driven_ by the tests. For example: + - `Hello()` <- how to write functions, return types. + - `Hello(name string)` <- arguments, constants. + - `Hello(name string)` <- default to "world" using `if`. + - `Hello(name, language string)` <- `switch`. +- Try and minimise the surface area of required knowledge. + - Thinking of examples that showcase what you're trying to teach without confusing the reader with other features is important. + - For example you can learn about `struct`s without understanding pointers. + - Brevity is king. +- Follow the [Code Review Comments style guide](https://github.com/golang/go/wiki/CodeReviewComments). It's important for a consistent style across all the sections. +- Your section should have a runnable application at the end \(e.g `package main` with a `main` func\) so users can see it in action and play with it. +- All tests should pass. +- Run `./build.sh` before raising PR. diff --git a/meta/exemplo.md b/meta/exemplo.md new file mode 100644 index 00000000..bae8ece7 --- /dev/null +++ b/meta/exemplo.md @@ -0,0 +1,17 @@ +# Exemplo de capítulo + +Introdução + +## Escrever o teste primeiro + +## Tentar executar o teste + +## Escrever o mínimo possível para fazer o teste rodar e verificar a saída do teste que houver falha + +## Escrever código o suficente para fazê-lo passar + +## Refatorar + +## Repetir a cada novo requerimento + +## Resumo diff --git a/meta/template.md b/meta/template.md deleted file mode 100644 index 338626c9..00000000 --- a/meta/template.md +++ /dev/null @@ -1,18 +0,0 @@ -# Template de capítulo - -Some intro - -## Write the test first - -## Try to run the test - -## Write the minimal amount of code for the test to run and check the failing test output - -## Write enough code to make it pass - -## Refactor - -## Repeat for new requirements - -## Wrapping up - From 3e55bd1918e94dd23fc01aec9801d93a4b08c7ac Mon Sep 17 00:00:00 2001 From: Lauren Ferreira Date: Sun, 7 Jul 2019 21:32:48 -0300 Subject: [PATCH 6/8] Trocar translating.md para traduzindo.md --- .gitbook.yaml | 2 +- README.md | 2 +- SUMMARY.md | 2 +- meta/{translating.md => traduzindo.md} | 0 4 files changed, 3 insertions(+), 3 deletions(-) rename meta/{translating.md => traduzindo.md} (100%) diff --git a/.gitbook.yaml b/.gitbook.yaml index 7ead1a35..f938ef2b 100644 --- a/.gitbook.yaml +++ b/.gitbook.yaml @@ -5,4 +5,4 @@ structure: summary: SUMMARY.md redirects: - translation: ./meta/translating.md + translation: ./meta/traduzindo.md diff --git a/README.md b/README.md index 34a871d7..fbe1d924 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,7 @@ Se tiver esse tipo de dúvida, crie uma Issue no GitHub e vou tentar achar tempo - _Esse projeto está em desenvolvimento_, tanto seu conteúdo original quanto sua tradução. Se tiver interesse em contribuir, por favor entre em contato. - Leia [contributing.md](meta/contributing.md) para algumas diretrizes. -- Quer ajudar com a tradução para o português? Leia [translating.md](meta/translating.md) e entenda como o processo de tradução está organizado. +- Quer ajudar com a tradução para o português? Leia [traduzindo.md](meta/traduzindo.md) e entenda como o processo de tradução está organizado. - Tem ideias? Crie uma issue! ## Explicação diff --git a/SUMMARY.md b/SUMMARY.md index 44a68966..16997268 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -40,5 +40,5 @@ - [Por que testes unitários e como fazê-los dar certo](meta/motivacao.md) - [Como contribuir](meta/contributing.md) -- [Como traduzir](meta/translating.md) +- [Como traduzir](meta/traduzindo.md) - [Exemplo de capítulo](meta/exemplo.md) diff --git a/meta/translating.md b/meta/traduzindo.md similarity index 100% rename from meta/translating.md rename to meta/traduzindo.md From 27602c3f82be2a1347720b7c5baacac13230f259 Mon Sep 17 00:00:00 2001 From: Lauren Ferreira Date: Sun, 7 Jul 2019 21:38:44 -0300 Subject: [PATCH 7/8] =?UTF-8?q?Remo=C3=A7=C3=A3o=20de=20par=C3=A1grafo=20e?= =?UTF-8?q?squecido=20em=20ingl=C3=AAs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- meta/motivacao.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/meta/motivacao.md b/meta/motivacao.md index b12be655..d99950a8 100644 --- a/meta/motivacao.md +++ b/meta/motivacao.md @@ -54,10 +54,6 @@ Nós **temos** que lidar com a complexidade do sistema conforme o conhecimento d Existem _diversas_ facetas na engenharia de software que mantêm um software maleável, como: -- - -There are _many_ facets of software engineering that keeps software malleable, such as: - - Capacitação do desenvolvimento - Em termos gerais, código "bom". Separação sensível de responsabilidades, etc - Habilidades de comunicação From 0bcee50f938ee91ba88c8fb28eb98225dfe5abef Mon Sep 17 00:00:00 2001 From: Lauren Ferreira Date: Wed, 10 Jul 2019 20:36:09 -0300 Subject: [PATCH 8/8] =?UTF-8?q?Corre=C3=A7=C3=B5es=20da=20revis=C3=A3o=20d?= =?UTF-8?q?o=20@devdrops?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- meta/motivacao.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/meta/motivacao.md b/meta/motivacao.md index d99950a8..4b2659c4 100644 --- a/meta/motivacao.md +++ b/meta/motivacao.md @@ -71,7 +71,7 @@ Sei que eu e muitas outras pessoas só _pensaram_ que estavam refatorando, mas e [Martin Fowler descreve como as pessoas entendem a refatoração errada aqui.](https://martinfowler.com/bliki/RefactoringMalapropism.html) -> No entanto, o termo "refatoração" costuma ser utilizado de forma inapropriada. Se alguém fala que um sistema ficará quebrado por alguns dais enquanto está sendo refatorado, pode ter certeza que eles não estão refatorando. +> No entanto, o termo "refatoração" costuma ser utilizado de forma inapropriada. Se alguém fala que um sistema ficará quebrado por alguns dias enquanto está sendo refatorado, pode ter certeza que eles não estão refatorando. Então o que é refatoração? @@ -83,9 +83,9 @@ Quando estudava matemática na escola, você provavelmente aprendeu fatoração. Para fazer isso você `fatora` os denominadores (você também pode conhecer como MMC, mínimo múltiplo comum), transformando a expressão em `2/4 + 1/4` que então pode se transformar em `3/4`. -Podemos tirar algumas lições importantes disso. Quando `fatoramos a expressão`, `não mudamos o que ela faz`. Ambas as expreções são iguais a `3/4`, mas facilitamos a forma como trabalhamos com esse resultado; trocar `1/2` por `2/4` torna nosso "domínio" mais fácil. +Podemos tirar algumas lições importantes disso. Quando `fatoramos a expressão`, `não mudamos o que ela faz`. Ambas as expressões são iguais a `3/4`, mas facilitamos a forma como trabalhamos com esse resultado; trocar `1/2` por `2/4` torna nosso "domínio" mais fácil. -Quando refatora seu código, você tenta encontrar formar de tornar seu código mais fácil de entender e "encaixar" no seu entendimento atual do que o sistema precisa fazer. Mas é extremamente importante que **o comportamento do código não seja alterado**. +Quando refatora seu código, você tenta encontrar formas de tornar seu código mais fácil de entender e "encaixar" no seu entendimento atual do que o sistema precisa fazer. Mas é extremamente importante que **o comportamento do código não seja alterado**. #### Exemplo em Go @@ -185,7 +185,7 @@ Ter um projeto onde os seus principais comportamentos são testados unicamente e ## Se testes unitários são tão bons, por que há resistência em escrevê-los? -De um lado, é possível ver pessoas (como eu) dizendo que testes unitários são importantes para a saúda do seu sistema a longo prazo, porque eles certificam que você possa continuar refatorando com confiança. +De um lado, é possível ver pessoas (como eu) dizendo que testes unitários são importantes para a saúde do seu sistema a longo prazo, porque eles certificam que você possa continuar refatorando com confiança. Do outro lado, é possível ver pessoas descrevendo experiências com testes unitários que na verdade _dificultaram_ a refatoração. @@ -223,11 +223,11 @@ Logo, _qual_ é o nível de abstração correto? Deixando testes de lado por um momento, é desejável "unidades" independentes e desacopladas dentro do seu sistema, centradas em torno de conceitos essenciais do seu domínio. -Gosto de imaginar essas unidades tão simples quanto blocos de Lego que têm APIs coerentes e que eu possa combinar com outros blocos para criar sistemas maiores. Por baixo dessas APIs pode haver várisas coisas (tipos, funções etc) colaborando para fazê-las funcionar conforme esperado. +Gosto de imaginar essas unidades tão simples quanto blocos de Lego que têm APIs coerentes e que eu possa combinar com outros blocos para criar sistemas maiores. Por baixo dessas APIs pode haver várias coisas (tipos, funções etc) colaborando para fazê-las funcionar conforme esperado. Por exemplo: se estiver escrevendo um banco em Go, você deve ter um pacote "conta". Ele vai te apresentar uma API que não vaza detalhes da implementação e é fácil de ser integrado. -Se tiver essas unidades que seguem essas propriedades, você consegue escrever testes unitários para suas APIs públicas. _Por definição_, esses testes só podem testar os comportamentos importantes. Por baixo dos panos dessas unidades, fico livre para refatorar a implementação o quanto eu precisar e os testes para a maior parte dela não deve me atrapalhar. +Se tiver essas unidades que seguem essas propriedades, você consegue escrever testes unitários para suas APIs públicas. _Por definição_, esses testes só podem testar os comportamentos importantes. Por baixo dos panos dessas unidades, fico livre para refatorar a implementação o quanto eu precisar e os testes para a maior parte dela não devem me atrapalhar. ### Mas são testes unitários, mesmo? @@ -250,7 +250,7 @@ O que podemos começar a ver é que essas facetas do desenvolvimento de software ### Testes unitários -- Nos dá a garantia para refatoração. +- Nos dão a garantia para refatoração. - Verificam e documentam o comportamento de nossas unidades. ### Unidades (bem definidas) @@ -258,7 +258,7 @@ O que podemos começar a ver é que essas facetas do desenvolvimento de software - Facilitam a escrita de testes unitários _significativos_. - Facilitam a refatoração. -Há um processo que nos ajuda a alcançar um ponto onde podemos refatorar nosso código para lidaar com a complexidade e manter nossos sistemas maleáveis? +Há um processo que nos ajuda a alcançar um ponto onde podemos refatorar nosso código para lidar com a complexidade e manter nossos sistemas maleáveis? ## Por que Desenvolvimento Orientado a Testes (TDD) @@ -277,12 +277,12 @@ O TDD aborda as leis que Lehman fala sobre e outras lições difíceis aprendida - Escrever um teste pequeno para uma unidade do comportamento desejado - Verificar que o teste falha com um erro claro (vermelho) - Escrever o mínimo de código para fazer o teste passar (verde) -- Refatorar +- Refatorar (azul) - Repetir Conforme você pratica, essa mentalidade vai se tornar natural e rápida. -Você vai esperar que esse ciclo de feedback não leve muito tempo e se sentir desconfortável se estiver em um estado em que seu sistema não está "verde" por isso poder indicar que você pode ter deixado algo passar. +Você vai esperar que esse ciclo de feedback não leve muito tempo e se sentir desconfortável se estiver em um estado em que seu sistema não está "verde", já que isso pode indicar que você pode ter deixado algo passar. Você sempre vai desenvolver de forma a criar funcionalidades pequenas & úteis confortavelmente reforçadas pelo feedback dos seus testes.