From 1528f485cfb316b81758e4c66ea58b3aa1d27d2e Mon Sep 17 00:00:00 2001 From: Rod Elias Date: Thu, 27 Mar 2025 18:03:30 -0300 Subject: [PATCH] docs: minor improvements --- context.md | 4 ++-- dependency-injection.md | 2 +- generics.md | 4 ++-- hello-world.md | 4 ++-- maps.md | 2 +- math.md | 12 ++++++------ mocking.md | 2 +- reflection.md | 2 +- revisiting-arrays-and-slices-with-generics.md | 6 +++--- roman-numerals.md | 4 ++-- sync.md | 4 ++-- 11 files changed, 23 insertions(+), 23 deletions(-) diff --git a/context.md b/context.md index 5e223b7e..ce7f59e9 100644 --- a/context.md +++ b/context.md @@ -144,9 +144,9 @@ func Server(store Store) http.HandlerFunc { } ``` -This makes this test pass but it doesn't feel good does it! We surely shouldn't be cancelling `Cancel()` before we fetch on _every request_. +This makes this test pass but it doesn't feel good, does it? We surely shouldn't be cancelling `Store` before we fetch on _every request_. -By being disciplined it highlighted a flaw in our tests, this is a good thing! +By being disciplined it highlighted a flaw in our tests and this is a good thing! We'll need to update our happy path test to assert that it does not get cancelled. diff --git a/dependency-injection.md b/dependency-injection.md index fdec3539..96a1deab 100644 --- a/dependency-injection.md +++ b/dependency-injection.md @@ -124,7 +124,7 @@ The test now passes. Earlier the compiler told us to pass in a pointer to a `bytes.Buffer`. This is technically correct but not very useful. -To demonstrate this, try wiring up the `Greet` function into a Go application where we want it to print to stdout. +To demonstrate this, try writing up the `Greet` function into a Go application where we want it to print to stdout. ```go func main() { diff --git a/generics.md b/generics.md index 0191ed5c..091b9618 100644 --- a/generics.md +++ b/generics.md @@ -94,7 +94,7 @@ The tests should now compile and pass. If you try making them fail you'll see th ### The problem with `interface{}` -Our `AssertX` functions are quite naive but conceptually aren't too different to how other [popular libraries offer this functionality](https://github.com/matryer/is/blob/master/is.go#L150) +Our `AssertX` functions are quite naive but conceptually aren't too different to how other [popular libraries offer this functionality](https://github.com/matryer/is/blob/master/is.go#L160) ```go func (is *I) Equal(a, b interface{}) @@ -659,4 +659,4 @@ A common path I've taken in other programming languages has been: > OK, I'd like to try to see if I can generalise this thing. Thank goodness I am so smart and good-looking because I use TDD, so I can refactor whenever I wish, and the process has helped me understand what behaviour I actually need before designing too much. - This abstraction feels nice! The tests are still passing, and the code is simpler -- I can now delete a number of tests, I've captured the _essence_ of the behaviour and removed unnecessary detail +- I can now delete a number of tests, I've captured the _essence_ of the behaviour and removed unnecessary details. diff --git a/hello-world.md b/hello-world.md index 3aed99c6..198d310c 100644 --- a/hello-world.md +++ b/hello-world.md @@ -47,7 +47,7 @@ func main() { } ``` -We have created a new function with `func`, but this time, we've added another keyword, `string,` to the definition. This means this function returns a `string`. +We have created a new function with `func`, but this time, we've added another keyword, `string`, to the definition. This means this function returns a `string`. Now create a new file called `hello_test.go` where we are going to write a test for our `Hello` function @@ -338,7 +338,7 @@ We've refactored our assertion into a new function. This reduces duplication and For helper functions, it's a good idea to accept a `testing.TB` which is an interface that `*testing.T` and `*testing.B` both satisfy, so you can call helper functions from a test, or a benchmark (don't worry if words like "interface" mean nothing to you right now, it will be covered later). -`t.Helper()` is needed to tell the test suite that this method is a helper. By doing this, when it fails, the line number reported will be in our _function call_ rather than inside our test helper. This will help other developers track down problems more easily. If you still don't understand, comment it out, make a test fail and observe the test output. Comments in Go are a great way to add additional information to your code, or in this case, a quick way to tell the compiler to ignore a line. You can comment out the `t.Helper()` code by adding two forward slashes `//` at the beginning of the line. You should see that line turn grey or change to another color than the rest of your code to indicate it's now commented out. +`t.Helper()` is needed to tell the test suite that this method is a helper. By doing this, when it fails, the line number reported will be in our _function call_ rather than inside our test helper. This will help other developers track down problems more easily. If you still don't understand, comment it out, make a test fail and observe the test output. Comments are a great way to add additional information to your code, or in this case, a quick way to tell the compiler to ignore a line. You can comment out the `t.Helper()` code by adding two forward slashes `//` at the beginning of the line. You should see that line turn grey or change to another color than the rest of your code to indicate it's now commented out. When you have more than one argument of the same type \(in our case two strings\) rather than having `(got string, want string)` you can shorten it to `(got, want string)`. diff --git a/maps.md b/maps.md index b5889795..18552630 100644 --- a/maps.md +++ b/maps.md @@ -127,7 +127,7 @@ Here we created a `Dictionary` type which acts as a thin wrapper around `map`. W The basic search was very easy to implement, but what will happen if we supply a word that's not in our dictionary? -We actually get nothing back. This is good because the program can continue to run, but there is a better approach. The function can report that the word is not in the dictionary. This way, the user isn't left wondering if the word doesn't exist or if there is just no definition (this might not seem very useful for a dictionary. However, it's a scenario that could be key in other usecases). +We actually get nothing back. This is good because the program can continue to run, but there is a better approach. The function can report that the word is not in the dictionary. This way, the user isn't left wondering if the word doesn't exist or if there is just no definition (this might not seem very useful for a dictionary. However, it's a scenario that could be key in other use cases). ```go func TestSearch(t *testing.T) { diff --git a/math.md b/math.md index 96eccdaa..fa029dd1 100644 --- a/math.md +++ b/math.md @@ -59,7 +59,7 @@ so they point in the appropriate directions for a given time. ## An Acceptance Test -Before we get too stuck in, lets think about an acceptance test. +Before we get too stuck in, let's think about an acceptance test. Wait, you don't know what an acceptance test is yet. Look, let me try to explain. @@ -320,13 +320,13 @@ I'm getting this one to pass. ### A recap on packages -At the moment, our acceptance tests are in the `clockface_test` package. Our tests can -be outside of the `clockface` package - as long as their name ends with `_test.go` they +At the moment, our acceptance tests are in the `clockface_test` package. Our tests can +be outside of the `clockface` package - as long as their name ends with `_test.go` they can be run. I'm going to write these radians tests _within_ the `clockface` package; they may never get exported, and they may get deleted (or moved) once I have a better grip on -what's going on. I'll rename my acceptance test file to `clockface_acceptance_test.go`, +what's going on. I'll rename my acceptance test file to `clockface_acceptance_test.go`, so that I can create a _new_ file called `clockface_test` to test seconds in radians. ```go @@ -388,7 +388,7 @@ ok clockface 0.011s ### Refactor -Nothing needs refactoring yet +Nothing needs refactoring yet. ### Repeat for new requirements @@ -576,7 +576,7 @@ So we've got the first part covered here - we know what angle the second hand will be pointing at in radians. Now we need to work out the coordinates. Again, let's keep this as simple as possible and only work with the _unit -circle_; the circle with a radius of 1. This means that our hands will all have +circle_: the circle with a radius of 1. This means that our hands will all have a length of one but, on the bright side, it means that the maths will be easy for us to swallow. diff --git a/mocking.md b/mocking.md index e4c99eda..6fbee11a 100644 --- a/mocking.md +++ b/mocking.md @@ -580,7 +580,7 @@ If your mocking code is becoming complicated or you are having to mock out lots Normally a lot of mocking points to _bad abstraction_ in your code. -**What people see here is a weakness in TDD but it is actually a strength**, more often than not poor test code is a result of bad design or put more nicely, well-designed code is easy to test. +**What people see here is a weakness in TDD but it is actually a strength**. More often than not poor test code is a result of bad design or put more nicely, well-designed code is easy to test. ### But mocks and tests are still making my life hard! diff --git a/reflection.md b/reflection.md index 63081206..54e601c1 100644 --- a/reflection.md +++ b/reflection.md @@ -2,7 +2,7 @@ **[You can find all the code for this chapter here](https://github.com/quii/learn-go-with-tests/tree/main/reflection)** -[From Twitter](https://twitter.com/peterbourgon/status/1011403901419937792?s=09) +[From X](https://x.com/peterbourgon/status/1011403901419937792?s=09) > golang challenge: write a function `walk(x interface{}, fn func(string))` which takes a struct `x` and calls `fn` for all strings fields found inside. difficulty level: recursively. diff --git a/revisiting-arrays-and-slices-with-generics.md b/revisiting-arrays-and-slices-with-generics.md index 6cc4786f..d77bf6f5 100644 --- a/revisiting-arrays-and-slices-with-generics.md +++ b/revisiting-arrays-and-slices-with-generics.md @@ -429,7 +429,7 @@ Practice combining TDD with good source control habits. Commit your work when yo Make an effort to do some research outside of Go, so you don't re-invent patterns that already exist with an already established name. -Writing a function takes a collection of `A` and converts them to `B`? Don't call it `Convert`, that's [`Map`](https://en.wikipedia.org/wiki/Map_(higher-order_function)). Using the "proper" name for these items will reduce the cognitive burden for others and make it more search engine friendly to learn more. +Writing a function that takes a collection of `A` and converts them to `B`? Don't call it `Convert`, that's [`Map`](https://en.wikipedia.org/wiki/Map_(higher-order_function)). Using the "proper" name for these items will reduce the cognitive burden for others and make it more search engine friendly to learn more. ### This doesn't feel idiomatic? @@ -441,12 +441,12 @@ Saying > This is not idiomatic -Without any more detail, is not an actionable, or useful thing to say. Especially when discussing new language features. +Without any more detail, is not an actionable, or useful thing to say, especially when discussing new language features. Discuss with your colleagues patterns and style of code based on their merits rather than dogma. So long as you have well-designed tests, you'll always be able to refactor and shift things as you understand what works well for you, and your team. ### Resources -Fold is a real fundamental in computer science. Here's some interesting resources if you wish to dig more into it +Fold is a real fundamental in computer science. Here's some interesting resources if you wish to dig more into it: - [Wikipedia: Fold](https://en.wikipedia.org/wiki/Fold) - [A tutorial on the universality and expressiveness of fold](http://www.cs.nott.ac.uk/~pszgmh/fold.pdf) diff --git a/roman-numerals.md b/roman-numerals.md index e82a9f1e..48970250 100644 --- a/roman-numerals.md +++ b/roman-numerals.md @@ -112,7 +112,7 @@ func TestRomanNumerals(t *testing.T) { numeral_test.go:20: got 'I', want 'II' ``` -Not much surprise there +Not much surprise there. ## Write enough code to make it pass @@ -673,7 +673,7 @@ Now that we have our functions to convert an arabic number into a roman numeral ## An intro to property based tests -There have been a few rules in the domain of Roman Numerals that we have worked with in this chapter +There have been a few rules in the domain of Roman Numerals that we have worked with in this chapter: - Can't have more than 3 consecutive symbols - Only I (1), X (10) and C (100) can be "subtractors" diff --git a/sync.md b/sync.md index 46c7e189..4ad894ac 100644 --- a/sync.md +++ b/sync.md @@ -149,9 +149,9 @@ By waiting for `wg.Wait()` to finish before making our assertions we can be sure ## Try to run the test ``` -=== RUN TestCounter/it_runs_safely_in_a_concurrent_envionment +=== RUN TestCounter/it_runs_safely_concurrently --- FAIL: TestCounter (0.00s) - --- FAIL: TestCounter/it_runs_safely_in_a_concurrent_envionment (0.00s) + --- FAIL: TestCounter/it_runs_safely_concurrently sync_test.go:26: got 939, want 1000 FAIL ```