sglavoie.com – Tag: Go

Book summary: 100 Go Mistakes and How to Avoid Them

Sébastien Lavoie — Sat, 24 Aug 2024 14:55:00 -0600

Go: Simple to learn but hard to master

Go outline

Go does not have:
- Type inheritance;
- Macros;
- Partial functions;
- Support for lazy variable evaluation;
- Support for immutability;
- Operator overloading;
- Pattern matching;
- …
Go is:
- Stable;
- Expressive;
- Fast to compile;
- Safe (type-safety);
- Simple;
- Excellent for concurrent programming (goroutines, channels).

Simple doesn’t mean easy

Concurrency in Go may be simpler than in other languages, but it is still hard to get right, as per this study.

100 Go mistakes

Learning from mistakes is efficient.
“the best time for brain growth is when we’re facing mistakes” (source).
“we can remember not only the error but also the context surrounding the mistake” (source).
Categories of mistakes
- Bugs
  - Bugs are very costly (source).
  - Bugs can be very dangerous (e.g., in the case of a radiation therapy machine).
- Needless complexity
  - Don’t over-complicate things.
- Weaker readability
  - “the ratio of time spent reading versus writing is well over 10 to 1” (source).
  - Nested code.
  - Data type representation.
  - Not using named result parameters.
- Suboptimal or unidiomatic organization
  - Utility packages.
  - Init functions.
- Lack of API convenience
  - Overusing any types.
  - Wrong creational pattern.
  - Blindly applying OOP principles.
- Under-optimized code
  - Lack of fundamental knowledge.
  - Impacted performance.
  - Floating-point accuracy.
  - Poorly parallelized execution.
  - Not knowing how to reduce allocations.
  - Data alignment.
- Lack of productivity
  - Know how to write efficient tests.
  - Use the standard library.
  - Use profilers and linters.

Code and project organization

1 - Unintended variable shadowing

A variable name declared in a block can be re-declared in a nested block (variable shadowing).

 go
 
 
 
// client is shadowed
var client *http.Client // will always be nil
 if tracing {
 client, err := createClientWithTracing()
 if err != nil {
 return err
 }
 log.Println(client)
 } else {
 client, err := createDefaultClient()
 if err != nil {
 return err
 }
 log.Println(client)
 }

Solutions
- Use a temporary variable name in the inner scope.
- Use the = operator instead of := in the inner scope. Leads to a single assignment. Error handling can be handled in the outer scope (client, err = ...).
- Be caution with reusing err as well.

2 - Unnecessary nested code

Put the happy path first and return early on all edge cases and errors.
Instead of using else blocks, use early returns.
Instead of checking for an happy path, check for the error path and return where possible.

3 - Misusing init functions

Refresher on init functions
- An init function is a special function that is executed before the main function. It takes no arguments and returns no values.
- Variables are initialized, the init function is called, and then the main function is called.
- Imported packages are initialized before the main function is called and before the init function in the main package is called because the main package depends on the imported packages.
- Packages can define multiple init functions, in which case they are executed in alphabetical order based on the source code file name. Hence, we should not depend on the order of execution of init functions as file names can change.
- The same source file can define multiple init functions, in which case they are executed in the order they are defined in the file.
- The underscore operator (_) can be used to import a package without using it. This is useful to execute the init function of a package without using the package itself.
- init functions cannot be invoked explicitly.
When to use init functions
- They should not be used to initialize variables, as error handling is limited (they don’t return errors, one must panic).
- When testing a package, the init function is executed before the tests are run.
- If side effects are achieved via variables, these become global variables, which pollute the global namespace. Any function in the package can access these variables, which can lead to unexpected behavior. Unit tests depending on such functions will be harder to write.
- The responsibility of error handling should be left up to the caller.
- They can be helpful to define static configurations, as is done in the init function of the Go blog.

4 - Overusing getters and setters

Go has no support for automatic getters and setters, and it is idiomatic to use direct access to fields.
When the use case justifies it, a getter should be named FieldName (not GetFieldName) and a setter should be named SetFieldName.

5 - Interface pollution

Go’s interfaces are satisfied implicitly (structural typing).
“The bigger the interface, the weaker the abstraction.” — Rob Pike
When to use interfaces
- Common behavior
  - The behavior is factored out into an interface when it is common to multiple types (e.g., sort.Interface).
- Decoupling
  - The implementation is decoupled from the interface, which allows for easier testing and swapping of implementations.
- Restricting behavior
  - The interface restricts the behavior of the type, which can be useful for enforcing constraints. For example, the io.Reader interface restricts the behavior of the type to reading. It is possible to enforce constraints such as with a getter interface that only has a Get method and prevents setting values.
Interface pollution
- Abstractions should be discovered, not invented. Only create interfaces when they are needed.
- Adding levels of indirection makes the code harder to understand.

6 - Interface on the producer side

Producer side refers to an interface defined in the same package as the type that satisfies it.
Consumer side refers to an interface defined in a package that uses it and which is independent of the package that implements the interface.
The client should determine the level of abstraction it needs.
This relates to the Interface segregation principle of SOLID.

7 - Returning interfaces

In many cases, this is a bad practice in Go.
“Be conservative in what you do, be liberal in what you accept from others.” — Transmission Control Protocol
- Return structs instead of interfaces.
- Accept interfaces if possible.
Interfaces might be returned (e.g., io.Reader), but this should be done with caution. It’s usually done when the interface itself is implemented on the producer side (e.g., standard library) and the consumer side (e.g., user code) is expected to use it.

8 - `any` says nothing

The interface{} type is a placeholder for any type. any is an alias for interface{} since Go 1.18.
It requires a type assertion to be used.
Using any does not convey any meaningful information about the type.
It will lead to issues compilation-wise.

9 - Being confused about when to use generics

A “type parameter” is a placeholder for a type that is specified when the function is called.
A constraint is a condition that the type parameter must satisfy (e.g., implement an interface like comparable).

 go
 
 
 
type intStringConstraint interface {
 ~int | ~string
 // ^--- union operator
}

The union operator (|) is used to specify that the type parameter must be either int or string.
The tilde (~) is used to restrict all the underlying types of the type parameter to the specified types.
Common uses and misuses
- Generics are useful to factor out common behavior (e.g, the sort interface).
  - Data structures (e.g., binary tree, linked list, heap).
  - Functions working with slice, map, channels of any type.
- Generics are not useful when the behavior is not common.
  - If the method of the type argument is called, then the generic should be removed in the function received and a type should be specified in the function parameter.
- Generics do not shine when they make the code more complex. Unnecessary abstraction should be avoided.

10 - Not being aware of the possible problems with type embedding

A type embedding is a way to reuse the fields and methods of a type in another type. The fields from that other type get “promoted” to the new type (i.e., they can be accessed directly from the new type, as well as through the embedded type).
Incorrect usage
- An example of a wrong use of type embedding is a sync.Mutex embedded in a struct. It will be available outside the struct and can be misused.
- It shouldn’t be used only as syntactic sugar to access the methods of the embedded type. Use a field instead.
- It shouldn’t promote fields that are not intended to be used outside the struct (e.g., sync.Mutex).
Correct usage
- A custom logger that wants to write and close may embed a io.WriteCloser interface so that both methods are available. They will be promoted to the new type and there won’t be a need to implement these methods simply to forward a call to the embedded type.
- Preventing type embeddings in public structs is probably the safest route.
Embedding vs. OOP subclassing
- Embedding is not subclassing. It is a way to reuse fields and methods of a type in another type. It is a form of composition.

11 - Not using the functional options pattern

Config struct
- This is limited because to bring flexibility and distinguish between the zero value and the default value, one must use pointers.
Builder pattern
- To keep chaining method calls, one should not return an error, which means validation is delayed.
- To have proper error handling along the way, it makes the configuration more complex than it needs to be.
Functional options pattern
- This pattern makes use of closures to set the configuration options, where the closure is an anonymous function being returned.
- The closure is called with the configuration struct as an argument, and it sets the configuration options.
- This pattern allows for validation of the configuration options and for the configuration to be set in a single call.
- It is a flexible pattern that allows for the configuration to be set in any order and for the configuration to be validated at the time of setting.
- One does not need to provide a default value for the configuration struct since the function accepts variadic arguments, which may be empty.

12 - Project misorganization

Project structure
- The project-layout is a great place to start for a complex application. Despite not being an official standard, it is a great and logically sound starting point.
Package organization
- There is no concept of subpackages in Go. Sub-directories are useful to have high cohesion.
- Hexagonal architecture group per technical layer.
- An alternative is to group by context (e.g., customer context, contract context).
- Avoid both nano and huge packages.
  - Nano packages probably mean there’s lack of understanding about the connections between the different files.
  - Huge packages dilute the meaning of the package.
  - Name a package after what they provide, not what they contain.
  - “Package names should be short, concise, expressive and, by convention, a single lowercase word”.
- Minimize what should be exported as much as possible to reduce coupling.

13 - Creating utility packages

utils, common, base… bad practice.
util is meaningless.
While nano packages should be avoided, if a few functions are highly cohesive and don’t belong anywhere else, it’s a good idea to keep them separate with good naming.
Make APIs expressive.

14 - Ignoring package name collisions

Naming a variable the same as a package name will shadow the package name.
Either rename the variable (redisClient := redis.NewClient()) or rename the import with an alias (import redisapi "mylib/redis").
The same is true for built-in functions like copy: they shouldn’t be shadowed.

15 - Missing code documentation

Simplifies how clients consume an API.
Helps in maintaining a project.
In Go, every exported element should be documented, starting with the name of the element being documented (e.g., Customer is ...). It should be a complete sentence ending with a period.
An element can be marked as deprecated with a comment starting with Deprecated: after the description of the element.
The convention to document a package is to have a comment at the top of the file with the package name and a description of the package, starting with // Package packageName .... The first line should be concise, then a blank line, then a more detailed description.
Comments at the top of the file will be omitted from the documentation if they are followed by a blank line and more comments.

16 - Not using linters

Automatic tool to analyze code and catch errors.
They help prevent mistakes automatically and consistently.

Data types

17 - Creating confusion with octal literals

Using 0o instead of 0 for octal literals is clearer.
Octal is still useful to express file permissions (e.g., 0644).
Go supports using underscores in numeric literals to improve readability (e.g., 1_000_000).

18 - Neglecting integer overflows

It won’t panic at runtime. They are silent bugs.
It will wrap around.
Use the math package to check for overflows.
Detecting integer overflow when incrementing
- Use math.MaxInt, math.MinInt, math.MaxUint, math.MinUint.
Detecting integer overflows during addition
- Use math.MaxInt - a < b or math.MaxUint - a < b.
Detecting integer overflows during multiplication
- Use math.MaxInt/a < b or math.MaxUint/a < b.

19 - Not understanding floating points

A mantissa is the significant part of a floating-point number.
The exponent is the power of 10 by which the mantissa is multiplied.
For float32, the mantissa is 23 bits and the exponent is 8 bits.
For float64, the mantissa is 52 bits and the exponent is 11 bits, the remaining bit is the sign bit.
It is best to avoid comparing by equality with floating-point numbers and instead use a tolerance (delta).
Use math.IsInf and math.IsNaN to check for infinity and NaN.
Group floating-point numbers together by their magnitude to reduce precision loss when adding and subtracting.
With calculations involving both addition/subtraction and multiplication/division, it is best to perform the multiplication/division first to reduce precision loss.

20 - Not understanding slice length and capacity

Slice data is stored contiguously in an array data structure.
A slice holds a pointer to the array, the length of the slice, and the capacity of the slice.
Trying to access an index greater than the length of the slice will result in a runtime panic, even though the capacity is greater.
Slicing a slice will create a new slice with the same underlying array, but with a different length and capacity.
The append function will create a new slice with a new underlying array if the capacity is exceeded.

21 - Inefficient slice initialization

Use make to initialize a slice with a specific length and capacity.
Set a length of 0 (2nd argument to make) and a capacity of n (3rd argument to make), which will reuse the same backing array until the capacity is exceeded.
One can also set only the length and use direct assignment instead of append (bars[i] = fooToBar(foo)). This is about 400% faster than using an empty slice.
If the length of the slice is already known, it is better to take advantage of it and set the length of the slice when initializing it.

22 - Being confused about nil vs. empty slices

A slice is empty if its length is equal to 0.
A slice is nil if it equals nil.
A nil slice is an empty slice.
A nil slice can be passed in a single line: s := append([]int(nil), 42).
A nil slice is marshaled as a null element, whereas a non-nil, empty slice is marshaled as an empty array.

23 - Not properly checking if a slice is empty

"[…] when designing interfaces, we should avoid distinguishing nil and empty slices, which leads to subtle programming errors".
“This principle is the same with maps. To check if a map is empty, check its length, not whether it’s nil”.
Do len(slice) != 0 instead of slice != nil.

24 - Not making slice copies correctly

The destination slice must have the same length as the source slice (or greater). Else, the copy will match the length of the destination slice and may be missing elements.
copy is the more idiomatic way to copy slices (vs. dst := append([]int(nil), src...)).

25 - Unexpected side effects using slice `append`

If the resulting slice as a length smaller than the capacity, the slice will be modified in place and will have unintended side effects.
To avoid side effects outside a given range of a slice, full slice expression can be used (e.g., s := []int{1, 2, 3}, then s[:2:2] will create a new slice with a length of 2 and a capacity of 2).

26 - Slices and memory leaks

Leaking capacity
- Slicing a huge slice to a smaller slice will keep the capacity of the original slice. This makes matters worst if the result of a slice is kept for many iterations in a loop.
- Instead, use copy to create a new slice with the necessary length.
Leakage with full slice expressions
- The issue is the same as with slicing.
- The solution is the same as with slicing.
Slice and pointers
- A slice holds a pointer to an array, so if the slice is kept, the array will be kept in memory.
- To avoid this, use copy to create a new slice with the necessary length.
- If however we want to keep the original capacity, we can set all the unneeded elements to nil explicitly. For instance, all elements but the first 2:

 go
 
for i := 2; i < len(foos); i++ {
 foos[i].v = nil
 }

27 - Inefficient map initialization

Maps are unordered collections of key-value pairs, where all keys are unique. They use hash tables under the hood.
Insertion can be an O(n) operation if the map is resized.
make can be used to initialize a map with a specific size (second argument to make, without capacity). This avoids having to grow the map and re-balancing all the buckets of 8 elements each.

28 - Maps and memory leaks

The number of buckets in a map cannot shrink. Removing elements from a map will not reduce the number of buckets.
Even the overflown buckets will not be reduced.
One possible solution: periodically copy the map to a new map.
- Downside: the amount of memory used will be doubled for a short period of time.
Another solution: update the value type of the map to store an array pointer.
- The peak memory consumed will be far less.
- The garbage collection will be more efficient.

29 - Comparing values incorrectly

== does not work for slices, maps, and functions.
reflect.DeepEqual could be used, but it’s about 100x slower than ==, and so might be better used for testing only.
If strict comparison is needed on structs and good performance is required, consider using a custom comparison function.

Control structures

30 - Ignoring the fact that elements are copied in range loops

In Go, every assignment leads to a copy of the value.
In a range loop, the value is copied, not the reference.
To update a slice with a range loop, one must use the index to update the slice, i.e., for i := range s { s[i] = ... }.
A classic for loop can be used to update the slice in place, i.e., for i := 0; i < len(s); i++ { s[i] = ... }.
Using a pointer to a slice will allow for the slice to be updated in place, but iterating over such a slice is less efficient for the CPU.

31 - Ignoring how arguments are evaluated in range loops

Looping over an array will copy the value of the array element.
Using a pointer to the array will allow for the array to be updated in place and will avoid copying values, which may be more efficient, especially on large arrays.
The range loop evaluates the expression to its right only once, so if the expression is a slice, the slice will not be updated in the loop.
To access updated elements of a slice during iteration with a range loop, one must use the index to access the element in the slice, not the value of the element, since the expression is copied to a temporary variable.

32 - Ignoring the impact of using pointer elements in range loops

Using a pointer to a slice when looping with a range loop can lead to storing the address of the temporary variable in the slice for all elements in the slice.
To avoid this issue, one can create a local variable for each element to be iterated over in the slice and then use the local variable in the loop to perform assignments.
Another solution is to use a range loop with the index, create a temporary variable by dereferencing the pointer, and then assign the temporary variable to the slice.

33 - Making wrong assumptions during map iterations

Maps don’t sort keys.
Insertion order is not preserved.
Iteration order is unspecified. This is a conscious language design choice so that developers don’t rely on the order of the keys.
One should work on a copy of a map if new elements are to be added or removed during iteration.

34 - Ignoring how the break statement works

break works on the innermost loop, whether that be a for, switch, or select.
To break outside of a loop, one can use a label.
A label can be an idiomatic way to break out of nested loops, as is done in the net/http package with a readlines: label.

35 - Using `defer` inside a loop

defer is a statement that schedules a function to be called when the surrounding function returns. That is, it won’t run on each iteration of the loop until it returns, if ever.
To avoid resource leaks like this, each iteration of the loop can use a separate function that is run and defers the cleanup.
Another solution is to use a closure, but this can be less readable.
A function call will decrease performance slightly, so if performance is a concern, the defer call should be handled manually before the loop.

Strings

36 - Not understanding the concept of a rune

A charset is a set of characters.
An encoding describes how to translate a character set into a sequence of bytes.
In Go, a string is a reference to an immutable slice of bytes.
A rune is a Unicode code point.
Source code in Go is encoded in UTF-8: string literals will then also be encoded in UTF-8.
UTF-8 is a variable-length encoding, where each code point is represented by one to four bytes. For instance, the string hello is represented by five bytes, but the string containing the character 汉 is represented by three bytes, which we can check with len("汉").
A rune is an alias for int32 (4 bytes = 32 bits).
The repository golang.org/x contains extensions to work with UTF-16 and UTF-32.

37 - Inaccurate string iteration

With the unicode/utf8 package, one can use utf8.RuneCountInString(s) to count the number of runes in a string.
Accessing specific runes can be done without converting the string if characters are in the ASCII range.
It is most useful to convert a string to a slice of runes when a specific rune is required by index.
Iterating over the runes with a for range loop returns the starting index of the rune and the rune itself.
Iterating with a for range using only the index returns the starting index of the rune and the byte value at that position.

38 - Misusing trim functions

Use TrimRight to remove trailing characters. Go backwards until a rune is not in the set of characters to be trimmed.
Use TrimSuffix to remove a suffix (only one substring occurrence).
Use TrimLeft to remove leading characters. Go forwards until a rune is not in the set of characters to be trimmed.
Use TrimPrefix to remove a prefix (only one substring occurrence).

39 - Under-optimized string concatenation

+= is inefficient for string concatenation because it creates a new string each time.
Use strings.Builder for efficient string concatenation.
Call Grow on the builder to allocate memory for the string.

40 - Useless string conversions

Working with []byte is more efficient than working with strings due to many interfaces in the standard library taking []byte as input, which avoids doing a conversion.
Most methods in the strings package have a []byte counterpart in the bytes package.

41 - Substrings and memory leaks

A substring shares the same backing array as the original string.
If the substring is kept, the original string will be kept in memory.
To avoid this, either use string([]byte(theString[:n])) to slice the needed part of the string or strings.Clone to create a new string.

Functions and methods

42 - Not knowing which type of receiver to use

Go does not pass values by reference.
A value receiver makes a copy of the value: changes are local to the method.
A pointer receiver passes the memory address of the value: changes are global to the value. Strictly speaking, this is still a copy, but the copy is made for a pointer.
Use a pointer receiver when:
- The method needs to mutate the receiver.
- The method receiver contains a field that cannot be copied.
- The receiver is a large struct.
Use a value receiver when:
- Enforcing immutability.
- The receiver is a map, func or chan.
- A slice that doesn’t have to be mutated.
- The receiver is a small struct or array with no mutable fields, like time.Time.
- The receiver is a basic type, like int, float64, or string.
Mixing value and pointer receivers can lead to confusion and bugs: this should generally be avoided (although the standard library shows some exceptions, like time.Time).
Defaulting to a value receiver is a good practice, unless there is a good reason to use a pointer receiver.

43 - Never using named result parameters

Only use named result parameters when they make the code more readable (e.g., returning two int can be ambiguous).
Use naked returns only when the function is short and the return values are clear.
For an interface definition, named result parameters are useful to document the return values.

44 - Unintended side effects with named result parameters

Named result parameters are initialized to their zero value.
Using named result parameters doesn’t mean one has to use naked returns: clarity is more important than brevity.

45 - Returning a nil receiver

A nil receiver is a pointer to a struct that has not been initialized.
Instead of returning a pointer to a struct (which will return a non-nil pointer to a nil struct), return nil directly.

46 - Using a filename as a function input

It is more idiomatic and flexible to use an io.Reader or io.Writer as an input to a function that reads or writes to a file: this abstracts the data source.
This allows for the function to be used with any type that implements the io.Reader or io.Writer interface, not just a file.
It makes testing easier, as one can pass in a bytes buffer instead of a file, for instance.

47 - Ignoring how defer arguments and receivers are evaluated

The arguments to a defer statement are evaluated when the defer statement is executed, not when the deferred function is executed.
- That means that if a variable is initialized with a zero value and passed to defer as is, the deferred function will receive the zero value.
- To avoid this pitfall, one can use a pointer to the variable, which will be evaluated when the deferred function is executed. The memory address will not change, but the value at that address will.
- Another solution is to use a closure to capture the value of the variable at the time the defer statement is executed.
  - This works because the values of the variables are evaluated when the closure runs, not when the closure is created.
In the case of a method receiver, data in the receiver is evaluated when the defer statement is executed, leading to the same situation as with arguments.
- A pointer receiver can be used to avoid this issue, as the updated value of the pointer will be visible to the deferred function when it is executed.

Error management

48 - Panicking

It is used to signal genuinely unexpected errors, such as programming errors (e.g., net/http checking for a status code outside the valid range).
Another use case for panic is when the application requires a dependency but fails to initialize it (e.g., a regular expression).

49 - Ignoring when to wrap an error

%w is used to wrap an error conveniently.
The %v directive will print the transformed error message, but %w will print the error message and the wrapped error message.
If a caller relies on unwrapping an error provided with %w, it leads to coupling: if the underlying implementation that is wrapped changes, the caller will break.
To mark an error, one should use a custom error type.

50 - Checking an error type inaccurately

errors.As is used to check if an error is of a specific type anywhere in the error chain.
errors.As should be used whenever error wrapping is used.

51 - Checking an error value inaccurately

A sentinel error is a predefined error that can be compared to an error value. It is about an “expected” error (e.g., sql.ErrNoRows and io.EOF).
Unexpected errors should be implemented as error types, implementing the error interface.
errors.Is is used to check if an error is equal to a sentinel error (not ==! if the error is wrapped, it will not be equal to the sentinel error).

52 - Handling an error twice

Logging the same error twice can lead to confusion.
Logging an error is handling an error! One should not both log and return an error.
Error wrapping is useful to provide context to an error when propagating it up the call stack.

53 - Not handling an error

The only way to explicitly ignore an error is to assign it to the blank identifier _. Adding a comment about why the error is ignored is a good practice.
Do not simply ignore the assignment.

54 - Not handling defer errors

Errors should be handled or explicitly ignored in defer functions.
To return an error to the caller via the defer function, one can use a named return parameter, assigning the error to it.
Instead of returning multiple errors from a defer function, it may be a good idea to log one error and return the other, depending on the context.

Concurrency: Foundations

55 - Mixing up concurrency and parallelism

Concurrency is about structuring a program, while parallelism is about running multiple tasks at the same time.
Concurrency enables parallelism.

56 - Thinking concurrency is always faster

A thread is the smallest unit of execution that can be scheduled by an operating system.
A goroutine is a lightweight thread managed by the Go runtime: it is context-switched on and off by an OS thread.
A goroutine has a memory footprint of 2 KB, while a thread has a memory footprint of ~2 MB.
There is a point of diminishing returns when creating too many goroutines: one must take into account the overhead of context switching and determine the size of the workload that will be processed by each goroutine.
It is often best to start with a sequential solution and use profiling tools to determine where to add concurrency.

57 - Being puzzled about when to use channels or mutexes

Synchronization between parallel goroutines is achieved with mutexes (mutex stands for mutual exclusion).
Channels are used to communicate between goroutines. If there are 3 goroutines and a third one needs results from the first two, a channel is the way to go.
Mutexes ensure exclusive access to a resource (e.g., a map).
Coordination or ownership of a resource is achieved with channels.
In general, mutexes are needed for parallel goroutines, whereas channels are needed for concurrent ones.

58 - Not understanding race problems

A data race occurs when two goroutines access the same variable concurrently and at least one of the accesses is a write.
sync/atomic provides atomic operations to avoid data races. It works only on primitive types.
Channels can be used to perform atomic operations on non-primitive types, then send the result over the channel.
Mutexes can be used to protect a critical section of code.
The absence of a data race doesn’t mean the code will be deterministic: it is possible for goroutines to be scheduled in different orders, leading to a race condition.
A buffered channel can lead to a data race because a receive from an unbuffered channel happens before the send, but a send to a buffered channel happens before the receive.

59 - Not understanding the concurrency impacts of a workload type

A worker pool can be based on GOMAXPROCS (the number of OS threads) to efficiently distribute the workload when a workload is CPU-bound.
When a workload is I/O-bound, the number of goroutines can be increased to handle more I/O operations concurrently, depending on the external systems.

60 - Misunderstanding Go contexts

A context is a way to pass deadlines, cancellation signals, and other request-scoped values across API boundaries and between processes.
context.Background is the root context, which is never canceled, has no values, and has no deadline, used when there is no parent context.
Deadline
- A deadline is a point in time when the context should be canceled, specified as either a time.Time or a time.Duration (time from now).
- Deferring the cancellation of a context can prevent a goroutine from being blocked indefinitely or leaking resources.
Cancellation signals
- context.WithCancel returns a copy of the parent context with a new Done channel.
Context values
- context.WithValue returns a copy of the parent context with a key-value pair.
A function that users wait for should take a context as an argument.
Prefer context.TODO() to context.Background() when a context is needed but there is no parent context, as it better represents the intent.

Concurrency: Practice

61 - Propagating an inappropriate context

Propagating a context is about passing a context from one goroutine to another.
A context should be passed to a goroutine carefully: if the context requires some values to be passed but the parent goroutine gets its context cancelled, the child goroutine will also be cancelled. This may be undesirable.
- To avoid this, create a custom struct implementing a context that never expires and that does not carry a cancellation signal, so the values can be passed without the risk of being cancelled.

62 - Starting a goroutine without knowing when to stop it

A goroutine might loop over the values received from a channel, but if the channel is never closed, this will be a resource leak.
Passing a context to a goroutine (e.g., to expect a file to be closed) is bad design. Instead, the parent goroutine should be responsible for closing the file by calling a defer function right after the resource used by another routine is created.

63 - Not being careful with goroutines and loop variables

Spinning up a goroutine inside a for loop and relying on the loop variable can lead to unexpected behavior.
Either assign the value of the loop variable to a new variable inside the loop or pass the loop variable as an argument to the goroutine. In the first case, the goroutine could be set up as a closure. In the second case, it would be a regular function call on an anonymous function.

64 - Expecting deterministic behavior using select and channels

The select statement is used to wait on multiple channels. If multiple channels are ready, one will be chosen semi-randomly.
Using an unbuffered channel with a select statement will block until a value is sent on the channel.
Using a single channel and then checking the message type is an option.
Using a default case in a select statement will allow the program to continue if a channel no longer receives values.
- This approach works well for multiple channels: when a select case is chosen, add an inner select statement to handle the channel. For instance, after a disconnection message, handle all remaining messages sent the another channel by looping over the channel inside that select case.

65 - Not using notification channels

A notification channel is a channel that is used to signal the completion of a task.
If no data is needed to be sent, a struct{} can be sent over the channel. This is clearer than sending a bool or int. An empty struct occupies no memory.

66 - Not using nil channels

Sending a message to a nil channel will block forever.
Receiving from a closed channel is a non-blocking operation: the zero value of the channel type will be returned.
When looping over multiple channels and using select, if one of the channels is closed, this will lead to a busy-wait loop.
- E.g., say we have two channels in a function that are to be “merged” such that data returned from that function comes from the two channels. If one of the channels is closed, the function will still keep looping over the now invalid select case.
To avoid this, one can use a nil channel to signal a channel is closed. The select case will be skipped if the channel is nil, avoiding the busy-wait loop.

67 - Being puzzled about channel size

An unbuffered channel (synchronous channel) has a size of 0: the sender blocks until the receiver receives data from the channel.
With a buffered channel, the sender will block only when the buffer is full.
An unbuffered channel enables synchronization between goroutines.
An unbuffered channel can be used as a notification channel via a channel closure (close).
When using worker pools, a buffered channel can be used to limit the number of tasks that can be processed concurrently, matching the number of goroutines in the pool.
Rate-limiting can be achieved with a buffered channel, where the buffer size is the number of tasks that can be processed concurrently.
In a buffered channel, the lower the value, the bigger the impact on CPU. The higher the value, the bigger the impact on memory.
Buffered channels can lead to obscure deadlocks.
It’s usually best to start with a channel of size 1 and perform benchmarks to determine the optimal size.
Queues tend to be close to full or close to empty anyways (source).

68 - Forgetting about possible side effects with string formatting

Printing the values in a context will evaluate the values at the time of the call, which could lead to a data race.
Acquiring a lock only when it’s required is best. This reduces side effects and possible deadlocks. This ties nicely with the fact that a function can go over the “error cases” before doing anything else that might require more resources (e.g., check the age of a customer is valid before acquiring a lock).

69 - Creating data races with append

To prevent data races with append, one can make a copy of the slice in each goroutine before appending to it.
If the slice is initialized in such a way that the backing array is shared between goroutines, there will not be a data race since the original slice will remain unchanged.
Updating a map from one goroutine will lead to a data race if another goroutine tries to read from the map at the same time, given that the hashing algorithm for maps introduces some randomness.

70 - Using mutexes inaccurately with slices and maps

A mutex is used to protect a critical section of code from being accessed by multiple goroutines at the same time.
A mutex is used to protect a shared resource, like a slice or a map.
If an operation is lightweight, it is better to use a mutex to protect the resource (protecting the whole function in the process).
If an operation is heavy, it is better to make a copy of the resource and then update the copy, then replace the original resource with the copy.

71 - Misusing `sync.WaitGroup`

Add must be called in the parent goroutine before the child goroutine is started.
Done must be called in the child goroutine when the child goroutine is finished.
Wait must be called in the parent goroutine after all child goroutines have been started.

72 - Forgetting about `sync.Cond`

sync.Cond is used to signal a condition to multiple goroutines.
The updater goroutine locks a mutex, updates the condition, unlocks the mutex, and then signals the condition.
The listener goroutine(s) lock the mutex, wait for the condition to be signaled, and then unlock the mutex.
- Lock/unlock is done to offset the fact that Wait unlocks the mutex and then relocks it when the condition is signaled.
If no goroutines are waiting for the condition when the call to Broadcast occurs, the signal is lost.

73 - Not using `errgroup`

errgroup provides tools to manage a group of goroutines and propagate errors.
It can be used to share context between goroutines to allow for cancellation of the group of goroutines upon the first error. If 3 calls are made in parallel and one of them fails fast with an error, the other two will be cancelled instead of waiting.

74 - Copying a sync type

sync.* types should never be copied.
If we have a value receiver receiving a struct containing a Mutex, for instance, it will be copied when passed to a function. This will lead to a data race.
To avoid the issue with a value receiver, either use a pointer receiver or make the mutex field a pointer.
The same issue will present itself if a function takes a sync.* type as an argument or if a field in a struct received as a function argument is a sync.* type.
go vet can catch these types of issues.

The standard library

75 - Providing a wrong time duration

Always use the time.Duration API to provide a time duration. Passing any int64 value would work, but the function accepts nanoseconds, which will be confusing.

76 - `time.After` and memory leaks

Resources created by time.After (e.g., a channel) are released only when the timer expires.
Using time.After inside a loop will create a new channel each time the loop iterates, leading to a memory leak. Each call to time.After will consume about 200 bytes. If this is a long-running loop with frequent events, this can be a significant memory leak (e.g., 5 million calls in an hour would be about 1 GB of wasted memory).
Use time.NewTimer instead, which will create a timer that can be reset, then listen for the timer to expire on the channel (<-timer.C).

77 - Common JSON-handling mistakes

When unmarshaling JSON, the json package will not set the fields of a struct to their zero values if the fields are not present in the JSON.
Type embedding in a struct can be problematic if the embedded type implements the json.Marshaler interface, which by virtue of being promoted will be used instead of the json.MarshalJSON method of the struct.
- Type embedding makes the parent struct implements interfaces of the embedded type.
If possible, use a named field instead of an anonymous field (type embedding) to avoid this issue.
Monotonic clocks guarantee that the time will always increase, even if the system clock is changed. This is useful for measuring time intervals.
- In Go, monotonic time is part of the same API that provides wall time.
- time.Equal does not take into account the monotonic clock, so it is possible for two times to be equal even if they are not.
- One can also strip away the monotonic time with time.Truncate(0).
To prevent time zone issues, use time.LoadLocationto load the desired time zone or usetime.UTC` to work with UTC time.
Using a map of any to unmarshal JSON may be convenient but has its drawbacks. For instance, numeric values will be unmarshaled as float64, even if they contain no decimals.

78 - Common SQL mistakes

“Forgetting that sql.Open doesn’t necessarily establish connections to a database”
- The behavior depends on the SQL driver.
- To make sure the connection is open, one should call Ping on the connection or use PingContext.
“Forgetting about connections pooling”
- SetMaxOpenConns should be set in any production-grade application to match the load the database can handle.
- If an application generates significant concurrent requests, the default value for SetMaxIdleConns (2) should be updated.
- If an application can face bursts of requests, one should set SetConnMaxIdleTime accordingly.
- SetConnMaxLifetime can be useful if an application is behind a load balancer, for example.
“Not using prepared statements”
- Prepared statements should be used in untrusted contexts.
“Mishandling null values”
- If the value of a column can be NULL, it should be structured as a pointer to receive nil values.
- Another approach is to use sql.NullString, sql.NullInt64, etc.
“Not handling row iteration errors”
- One should check rows.Err after iterating over rows to check for errors. This is because rows.Next can stop iterating over rows if an error occurs as well as when all rows have been read.

79 - Not closing transient resources

HTTP body
- The response body should be closed to avoid resource leaks (this is done automatically on the server side). This can be done conveniently with defer function that should call resp.Body.Close().
- The body should be closed even if it was not read (e.g., just checking the status code).
  - The body should be read to have a “keep-alive” connection (io.Discard is efficient for this purpose).
sql.Rows
- Rows should be closed to release the database connection.
os.File
- When closing a file in a defer function, the error should be sent back to the parent function to be handled in case of error while closing a writable file, for instance.
- If a write should be committed immediately, the file should be flushed before closing it with file.Sync() (this is a synchronous operation).

80 - Forgetting the return statement after replying to an HTTP request

http.Error does not stop the handler’s execution.
After calling http.Error, the handler should return to stop the execution.

81 - Using the default HTTP client and server

HTTP client
- The default client does not specify any timeouts.
HTTP server
- Just like the client, default timeouts should be overridden in production applications to avoid abuse and resource leaks.

Testing

82 - Not categorizing tests

They should be organized as per the testing pyramid:
- Unit tests: test a single function or method.
- Integration tests: test the interaction between multiple components.
- End-to-end tests: test the entire system.
It is not always necessary to run all tests at different stages of a project.
One can add a build flag such as // go:build integration to run integration tests only when needed.
- By default, files without a build flag will be run. Use go test --tags=integration -v . to run integration tests.
- It is possible to include negation in the build flag, e.g., // go:build !integration.
- Build tags apply to the whole file, not individual tests.
Using environment variables may be a better approach than build flags, because one can forget about existing tests that are being ignored and not explicitly flagged as such.
- Each test can then decide to check for environment variables being set and use t.skip to skip the test if the environment variable is not set.
Use testing.Short() in a conditional statement to skip long-running tests when running tests with the -short flag.

83 - Not enabling the `-race` flag

In Go, the race detector is a tool used at runtime to find data races.
- It is really useful, but brings quite a performance hit (5-10x memory, 2-20x execution time).
Concurrent code should be tested thoroughly to make use of the -race flag.
To avoid false positives in data race detections, one can use a loop to run the logic of the test multiple times.
If needed, // go:build !race can be used to exclude tests from running with the -race flag.

84 - Not using test execution modes

t.Parallel can be used to run tests in parallel.
- Sequential tests run first, then all parallel tests run at the same time (up to GOMAXPROCS, unless configured otherwise on the command-line).
There exists a -shuffle flag to randomize the order of tests, which isolates tests from each other.
- Using -v flag along with -shuffle will print the seed used to shuffle the tests, which can be useful to reproduce results from a CI environment.

85 - Not using table-driven tests

They are shorter and more readable than traditional tests.
They make refactoring tests easier.
They make test function names clearer/shorter.

86 - Sleeping in unit tests

Sleeping in a test can mean the test is flaky, especially when testing concurrent code.
Implementing a retry strategy is better than using a passive time.Sleep in a test.
- The testify package provides an Eventually function that can be used to retry a test function a number of times.
If a test can be synchronized, using a channel to receive the value from a goroutine to be tested can lead to deterministic results with no need for a sleep. This strategy can also implement a timeout using a select with a time.After case.

87 - Not dealing with the time API efficiently

Do not rely on time.Now in a function. If it must be tested, the time functionality could be injected as a dependency.
Even better, a function should allow receiving a time.Time as an argument, so that the caller can provide the needed value.
Time should also not be stored in a global variable, as all tests will share the same time, preventing them from running in parallel.
Whenever possible, testing time should be abstracted away from the code being tested.

88 - Not using testing utility packages

httptest package
- It can be used to test HTTP handlers.
- Instead of spinning up Docker, a fake server can be used to test the HTTP client.
iotest package
- io.Reader and io.Writer can be tested with this package.
- It can be used to test edge cases, such as reading a file that is too large or to make sure a reader is resilient against errors (e.g., network error).

89 - Writing inaccurate benchmarks

Use testing.B to run benchmarks. Then run go test -bench=., optionally adding the flag -benchtime=2s to run the benchmark for 2 seconds (default is 1 second).
Use b.ResetTimer after an expensive setup to reset the timer.
If the expensive call must be done for each iteration in the testing loop, then one can use b.StopTimer and b.StartTimer to stop and start the timer, respectively.
perflock can be used to lock the CPU frequency to avoid performance fluctuations during benchmarking.
Micro-benchmarks should be avoided, as they can be misleading. benchstat can be used to compare benchmarks. For instance, run go test -bench=. -count=10 | tee stats.txt to save the results to a file, then run benchstat stats.txt to compare the results.
Reusing the same variable in a benchmark can lead to incorrect results, as the compiler may optimize the code. To avoid this, use b.N to create a new variable for each iteration.
Forcing a benchmark to recreate data for each iteration of a loop may prevent CPU caching from affecting the results.

90 - Not exploring all the Go testing features

Use go test -coverprofile=coverage.out ./... in combination with go tool cover -html=coverage.out to generate a coverage report.
Test exposed behavior by creating a separate package so that unexported elements and internals are not tested.
testing.T can be used to test the behavior of a function, while testing.B can be used to test the performance of a function.
t.Cleanup can be used to clean up resources after a test (e.g., close a database connection).
When multiple cleanup functions are needed, they will be executed in reverse order of registration (LIFO), just like using defer.
TestMain can be used to set up and tear down resources for all tests in a package.

Optimizations

91 - Not understanding CPU caches

Mechanical sympathy is about understanding the hardware to write efficient code.
Most modern CPU architectures have three levels of cache: L1, L2, and L3.
L2 is about 4 times slower than L1, and L3 is about 10 times slower than L2.
L3 is a victim cache containing only data evicted from L2.
Access to main memory is between 50 and 100 times slower than access to L1 cache.
A cache line is the smallest unit of data that can be transferred between the cache and main memory. When first accessible a memory location, it results in a compulsory miss. Once the cache line is copied to the cache, subsequent accesses to the same memory location and contiguous ones will result in a cache hit.
A struct of slices can be about 20% faster than a slice of structs, because of spatial locality. For 16 elements, it may require 2 cache lines instead of 4 for a struct containing fields with slices.
Data structures affect predictability at the CPU level.
- Unit stride is when the CPU can predict the next memory location to access. All values are contiguous in memory.
- Constant stride is when the CPU can predict the next memory location to access (e.g., read every two elements of a slice), but the values are not contiguous in memory.
- Non-unit stride is when the CPU cannot predict the next memory location to access. The values are not contiguous in memory. This would be the case for a linked list or a slice of pointers.
Cache placement policy works roughly with the principle of least recently used (pseudo-LRU). When a cache line is full, the least recently used cache line is evicted.
Conflict misses happen because the cache is partitioned into sets, and two memory locations map to the same set. This can be avoided by aligning data structures to the cache line size.
A critical stride accesses memory addresses with the same set index, leading to a conflict miss.
This is why micro-benchmarking can be misleading: if the production system uses a different cache architecture, the results may be widely different.

False sharing is when two threads access different variables that are on the same cache line, and at least one of the goroutines is a writer.
This causes the cache line to be invalidated.
One solution is to add padding to the struct to ensure that the variables are on different cache lines, so that the same cache line is not copied across different logical cores.
Another approach is to use channels to communicate between goroutines, which will avoid false sharing, instead of having two goroutines share the same struct.

93 - Not taking into account instruction-level parallelism

Data hazards occur when an instruction depends on the result of a previous instruction (e.g., read and increment a variable).
Control hazards occur when the CPU cannot predict the next instruction to execute (e.g., conditionals).
Sometimes, introducing a temporary variable can help the CPU predict the next instruction and parallelize the execution.
One should remain cautious about micro-optimizations, since the Go compiler keeps evolving, and the generated assembly code may change.

94 - Not being aware of data alignment

"[…] a variable’s memory address should be a multiple of its own size": this is the principle of data alignment.
A struct size must be a multiple of the word size (8 bytes on 64-bit systems).
A struct being an atomic unit, it should be aligned to the word size, as it won’t be reorganized by the compiler. The compiler only adds padding to the fields to guarantee data alignment.
Rule of thumb: organize structs by size, from largest to smallest, to avoid padding. This leads to better spatial locality and cache usage.

95 - Not understanding stack vs. heap

Stack is the default memory. LIFO. Stores all local variables for a goroutine.
Currently, each goroutine initially gets 2 KB of stack space (contiguous memory, to preserve data locality), which can grow up to 1 GB.
A stack frame is created for each function call, and it is destroyed when the function returns. The stack frames pile up from accessing different functions inside a given goroutine.
A stack is self-cleaning: it requires no garbage collection. Each goroutine has its own stack.
Using pointers, slices, and maps will allocate memory on the heap. One reason is that memory addresses from a stack frame coming from a returned function could not be accessed anymore with a stack.
The memory heap in Go is managed by the garbage collector and is shared among all goroutines. Variables that could still be referenced after exiting a function are stored on the heap.
Allocations on the stack are trivial and faster than on the heap. The stack is also more cache-friendly.
Escape analysis is a compiler optimization that determines whether a variable can be allocated on the stack or the heap.
- “Sharing up” escapes to the heap (need a reference from a context that is about to be destroyed).
- “Sharing down” stays on the stack (no reference to the variable outside the function).
- Global variables are stored on the heap, because they can be shared across goroutines.
- A pointer sent to a channel will escape to the heap.
- A variable referenced by a value sent to a channel.
- When a local variable is too large to fit on the stack.
- When building a program, the -gcflags "-m" flag can be used to see the escape analysis results.

96 - Not knowing how to reduce allocations

The Reader interface takes in a slice of bytes and returns the number of bytes read and an error. If it had been the other way around, the slice would always escape to the heap.
sync.Pool can be used to reduce the number of allocations. It is a pool of objects that can be reused. E.g., when writing a slice of bytes to a buffer, the buffer can be reused.
sync.Pool is thread-safe.

97 - Not relying on inlining

Mid-stack inlining is when the compiler inlines a function call that is in the middle of the stack, not at the top (e.g., main calls foo, which calls bar, both functions are simple, so bar is inlined in foo and foo is in turn inlined in main).
Slow vs. fast paths can be optimized by the compiler. The slow path can be extracted to a separate function, which will be inlined in the fast path (“fast-path inlining technique”).

98 - Not using Go diagnostics tooling

Profiling
- With profiling, one can see where the program is spending most of its time. pprof is the Go profiler.
- There are different profiles: CPU (time spent), goroutine (stack traces of ongoing routines), heap (check memory leaks and current allocations), mutex (check time spent in locking calls), block (see where goroutines waits on synchronous operations).
- A profile can be generated while benchmarking: go test -bench=. -cpuprofile profile.out. This profile can be used with go tool pprof -http=:8080 profile.out.
- Heap profiling
  - It’s a good idea to force garbage collection before dumping the heap profile to avoid false assumptions. This can be done via the web UI at http://localhost/debug/pprof/heap?gc=1.
  - Snapshots can be compared with go tool pprof -http=:8080 -diff_base <file2> <file1>.
- Goroutine profiling
  - We can inspect to check for “goroutine leaks”.
- Block profiling
  - Useful to check performance affected by blocking calls. Must call runtime.SetBlockProfileRate to enable it. This profiler stays on until the program ends.
- Mutex profiling
  - Useful to check performance affected by mutex locks. Must call runtime.SetMutexProfileFraction to enable it. This profiler stays on until the program ends.
- A single profiler should be enabled at a time.
Execution tracer
- Used to check how garbage collection performs, how goroutines are scheduled, and how the scheduler behaves.
- It can be enabled with go test -bench=. -v -trace=trace.out or by downloading a trace file with /debug/pprof/trace?debug=0.
- The granularity of the tracer is per goroutine (unlike CPU profiling, which is per function).

99 - Not understanding how the GC works

debug.FreeOSMemory() can be used to force the garbage collector to release memory to the OS.
GODEBUG=gctrace=1 can be used to see the garbage collector in action.
One can force a large allocation of memory with something like var min = make([]byte, 1_000_000_000) so that the garbage collector will only trigger once the heap reaches twice the size of the allocation, which can reduce the impact on latency if otherwise many garbage collections would be triggered in a short period of time. On most systems, this leads to a lazy allocation (in the virtual address space). This is useful when the heap peak is known in advance.

100 - Not understanding the impacts of running Go in Docker and Kubernetes

CPU throttling can occur in Docker and Kubernetes, leading to performance degradation.
GOMAXPROCS should be set to the number of CPUs available to the container.

Resources and references

Book summary: Dive into Design Patterns

Sébastien Lavoie — Sat, 09 Mar 2024 12:53:00 -0600

Introduction

In the vast expanse of software engineering, design patterns and principles stand as lighthouses, guiding developers through the complex process of crafting robust, scalable, and maintainable software. Among these patterns, the Object-Oriented Programming (OOP) principles, Software Design Principles, and various design patterns provide a framework that seasoned and novice developers alike can leverage to solve common software design challenges. This article constitutes a book summary of Dive into Design Patterns written by Alexander Shvets. Beautifully illustrated, it delves into the core aspects of OOP, explores essential software design principles, and unveils a catalog of design patterns categorized into Creational, Structural, and Behavioral patterns. Here, each section is crafted to mimic the same structure as the book to offer a concise yet (hopefully) comprehensive overview, equipped with examples and analogies to illuminate these concepts further.

A brief OOP overview

Class attributes are called fields.
Methods define the behavior of a class.
Fields and methods are the members of their class.
Objects are concrete instances of a class.
Class hierarchies
- Parent = superclass — inherit from parent.
Abstraction: models the behaviors of a real-world object.
Encapsulation
- Hide parts of state and behaviors, interfacing with a simpler abstraction (e.g., starting a car engine doesn’t require knowing anything about mechanics).
- Private fields and methods are hidden outside of a class.
- Protected fields and methods are also hidden outside of a class but accessible to subclasses.
Interfaces look like classes with methods only.
Inheritance (arrow with empty triangle head, going from subclass to parent class)
- Build subclasses on top of superclasses.
- Allows code reuse.
- Subclasses automatically share the same interface as their parent class.
- One class inherits interface and implementation of another and can extend it. It can be treated as the superclass and depends on it.
Polymorphism
- The real type of an object is not required to be known to use it (e.g., if a class inherits from Animal and implements an abstract method makeSound, then we can call makeSound on that class regardless of what type of animal this is).
Relations between objects
- Dependency (dashed lined with arrow)
- Code that depends on interfaces or abstract classes lead to weaker dependency between classes.
- One class can affect the code from another class.
- Association (simple arrow pointing to the object being used, bi-direction allowed)
- When an object uses or interacts with another.
- One class knows about the other and uses it.
- Aggregation (line with empty diamond at the container end, an arrow at the end pointing toward the component)
- One object “has” a collection of others and serves as a container (e.g., a department has many professors).
- One class is made of another one and depends on it.
- The component can exist without the container.
- Composition (drawn like an aggregation, filling in the diamond)
- Specific kind of aggregation, where the component can only exist as part of the container.
- Like aggregation, but the first class also manages the life cycle of the class it depends on.
- Implementation
- One class defines methods from an interface. The class can be treated as the interface and depends on it.

Introduction to Design Patterns

Design patterns are solutions to common problems.
A pattern is a general concept for solving a particular problem.
A pattern is more high-level than an algorithm.
Architectural patterns are high-level. They are used to design the architecture of an entire application and can usually be implemented in any programming language.
Creational patterns are a way to increase flexibility and code reuse with object creation mechanisms.
Structural patterns are a way of assembling objects/classes into larger structures, keeping structures flexible and efficient.
Behavioral patterns deal with effective communication and assignment of responsibilities between objects.

Software Design Principles

Features of good software design include:

Code reuse
Extensibility

Design Principles

Encapsulate what varies.
- Minimize the effect caused by changes.
Program to an interface, not an implementation.
- A design can be seen as flexible when it doesn’t break if it can be extended without breaking existing code.
Favor composition over inheritance.
- Problems:
  - A subclass must implement all abstract methods from the superclass even if they’re not used.
  - Behavior of overridden methods must remain compatible with the base class.
  - The superclass is not well encapsulated, because all subclasses are aware of its implementation details. Furthermore, if a subclass needs to be extended, the superclass might be modified to accommodate this need.
  - Changes in the superclass can break the subclasses, leading to tight coupling.
  - It can lead to the creation of many hierarchies of classes to combine them over multiple dimensions.
- Inheritance represents the “is a” relationship, while composition represents a “has a” relationship.

SOLID Principles

Single-responsibility principle: “a class should have just one reason to change”.
Open-closed principle: classes should be open for extension but closed for modification.
Liskov Substitution Principle: when extending a class, you should be able to pass objects of the subclass in place of objects of the parent class without breaking the client code.
- Parameter types in a method of a subclass should match or be more abstract than parameter types in the method of the superclass.
- The return type in a method of a subclass should match or be a subtype of the return type in the method of the superclass.
- A method in a subclass shouldn’t throw types of exceptions which the base method isn’t expected to throw.
- A subclass shouldn’t strengthen pre-conditions, e.g. if a parameter requires an int, the subclass shouldn’t restrict the int to be positive.
- A subclass shouldn’t weaken post-conditions, e.g. if a database connection is expected to be closed in a class, don’t leave it open in a subclass.
- Invariants of a superclass must be preserved. For this, it’s safer to add fields to a class rather than modify existing ones.
- A subclass shouldn’t change values of private fields of the superclass, this is possible e.g. in Python or JavaScript where private members aren’t even protected.
Interface Segregation Principle
- Clients shouldn’t be forced to depend on methods they do not use, trim the fat off of big interfaces.
Dependency Inversion Principle
- High-level classes shouldn’t depend on low-level classes. Both should depend on abstractions. Abstractions shouldn’t depend on details. Details should depend on abstractions.

Catalog of Design Patterns

Creational Design Patterns

These patterns deal with object creation mechanisms, trying to create objects in a manner suitable to the situation.

Factory Method (virtual constructor)

Analogy
- The hiring process (factory method) of a company (client) may differ for each department (concrete creator), which will hire employees (products of the concrete creator).
When to use it
- "[…] you don’t know beforehand the exact types and dependencies of the objects your code should work with".
- To provide users of your library or framework with a way to extend its internal components.
- To save system resources by reusing existing objects instead of rebuilding them each time.
Implementation
- Define an interface that all products will implement.
- Add a factory method to the creator class.
- In the creator’s code, replace direct calls to product constructors with calls to the factory method.
- The factory method might need a parameter to decide which product type to create.
- Initially, the factory method might have a switch or similar logic to decide which product to instantiate.
- Create subclasses of the creator for each product type, overriding the factory method to handle specific product creation.
- Either create more subclasses or use a parameter in the factory method to specify the product type if there are many product types.
Pros
- No tight coupling between the creator and the concrete products.
- Single Responsibility Principle: the creator is responsible for creating products, and the products are responsible for their own creation.
- Open/Closed Principle: you can introduce new product types without changing the existing code.
Cons
- The code might become more complicated than it should be.
Relation to other patterns
- Abstract Factory is a more complex version of Factory Method.
- Factory Method is a specialization of Template Method.
- Prototype doesn’t require subclassing, but it’s not always possible to use it with a Factory Method.

 go
 
 
 
package main

import "fmt"

// Vehicle is the product
type Vehicle interface {
 Brake() string
 Drive() string
}

// VehicleFactory is the abstract factory
type VehicleFactory interface {
 CreateVehicle(vehicleType string) Vehicle
}

// CheapVehicleFactory is a concrete factory producing cheap stuff
type CheapVehicleFactory struct{}

func (f *CheapVehicleFactory) CreateVehicle(vehicleType string) Vehicle {
 switch vehicleType {
 case "Car":
 return &CheapCar{}
 case "Bike":
 return &CheapBike{}
 default:
 return nil
 }
}

// NiceVehicleFactory is a concrete factory producing nice stuff
type NiceVehicleFactory struct{}

func (f *NiceVehicleFactory) CreateVehicle(vehicleType string) Vehicle {
 switch vehicleType {
 case "Car":
 return &NiceCar{}
 case "Bike":
 return &NiceBike{}
 default:
 return nil
 }
}

// CheapCar is a concrete product implementing the Vehicle interface that's not so reliable
type CheapCar struct{}

// NiceCar is a concrete product implementing the Vehicle interface that's more likely to work
type NiceCar struct{}

// CheapBike is what it is
type CheapBike struct{}

// NiceBike is nice
type NiceBike struct{}

func (c *CheapCar) Brake() string {
 return "Squeeeeeeeak..."
}

func (c *NiceCar) Brake() string {
 return "Shhh."
}

func (c *CheapCar) Drive() string {
 return "Vroom poof poof vroom poof poof vroom"
}

func (c *NiceCar) Drive() string {
 return "VROOOOOM"
}

func (b *CheapBike) Brake() string {
 return "iiiiiiiiik"
}

func (b *NiceBike) Brake() string {
 return "(silence)"
}

func (b *CheapBike) Drive() string {
 return "kwik kwik kwik"
}

func (b *NiceBike) Drive() string {
 return "(silence)"
}

func produceVehicles(factory VehicleFactory) {
 car := factory.CreateVehicle("Car")
 fmt.Println("Car:")
 fmt.Println("drive:", car.Drive())
 fmt.Println("stop: ", car.Brake())

 bike := factory.CreateVehicle("Bike")
 fmt.Println("Bike:")
 fmt.Println("ride: ", bike.Drive())
 fmt.Println("brake:", bike.Brake())
}

func main() {
 momsGarage := &CheapVehicleFactory{}
 uncleBobsMansion := &NiceVehicleFactory{}

 fmt.Println("Cheap Vehicles\n-----------------")
 produceVehicles(momsGarage)

 fmt.Println("\nNice Vehicles\n---------------")
 produceVehicles(uncleBobsMansion)

 // Output:
 /*
 Cheap Vehicles
 -----------------
 Car:
 drive: Vroom poof poof vroom poof poof vroom
 stop: Squeeeeeeeak...
 Bike:
 ride: kwik kwik kwik
 brake: iiiiiiiiik

 Nice Vehicles
 ---------------
 Car:
 drive: VROOOOOM
 stop: Shhh.
 Bike:
 ride: (silence)
 brake: (silence)
 */
}

Abstract Factory

Analogy
- A car manufacturing company has different (abstract) factories in different parts of the world to produce vehicle whose requirements are adapted to the local needs.
When to use it
- It can create families of related or dependent objects without the need to specify their concrete classes.
- It makes the system independent from how the objects are created.
- It can be used where the set of objects may change dynamically while keeping the same functionality.
Implementation
- Define the abstract factory interface.
- Create concrete factory classes.
- Define the product interfaces.
- Create concrete product classes.
- Use the factory.
Pros
- Isolation from concrete classes.
- Can swap product families.
- Makes products consistent.
Cons
- More complex than the Factory Method pattern.
- More difficult to extend, having the need to change many interfaces.
- Works best with sets of families that don’t change too much or too often.
Relation to other patterns
- It can use the Factory Method to create the products.
- Builder allows constructing more complex objects one step at a time.
- Prototype can be used when creating products by cloning prototypes.

 go
 
 
 
package main

import "fmt"

// Product interfaces
type Car interface {
 Drive() string
}
type Bicycle interface {
 Ride() string
}

// Concrete products
type MercedesCar struct{}
type BMWCar struct{}
type CannondaleBicycle struct{}
type SpecializedBicycle struct{}

func (t *MercedesCar) Drive() string {
 return "Driving Mercedes"
}
func (t *BMWCar) Drive() string {
 return "Driving BMW"
}
func (t *CannondaleBicycle) Ride() string {
 return "Riding Cannondale"
}
func (t *SpecializedBicycle) Ride() string {
 return "Riding Specialized"
}

// Abstract factory
type VehicleFactory interface {
 CreateCar() Car
 CreateBicycle() Bicycle
}

// Concrete factories
type MercedesFactory struct{}
type BMWFactory struct{}
type SpecializedFactory struct{}

func (t *MercedesFactory) CreateCar() Car {
 return &MercedesCar{}
}

// Let's assume Mercedes make Cannondale bicycles
func (t *MercedesFactory) CreateBicycle() Bicycle {
 return &CannondaleBicycle{}
}

func (t *BMWFactory) CreateCar() Car {
 return &BMWCar{}
}

// Let's assume BMW also makes Specialized bicycles
func (t *BMWFactory) CreateBicycle() Bicycle {
 return &SpecializedBicycle{}
}

// Let's assume Specialized makes its own bicycles
func (t *SpecializedFactory) CreateBicycle() Bicycle {
 return &SpecializedBicycle{}
}

func produceVehicles(factory VehicleFactory) {
 car := factory.CreateCar()
 fmt.Println(car.Drive())

 bicycle := factory.CreateBicycle()
 fmt.Println(bicycle.Ride())
}

func main() {
 mercedesFactory := &MercedesFactory{}
 bmwFactory := &BMWFactory{}

 fmt.Println("Mercedes vehicles:")
 produceVehicles(mercedesFactory)

 fmt.Println("\nBMW vehicles:")
 produceVehicles(bmwFactory)

 // This doesn't work because SpecializedFactory doesn't implement CreateCar()
 // produceVehicles(&SpecializedFactory{})

 // Output:
 /*
 Mercedes vehicles:
 Driving Mercedes
 Riding Cannondale

 BMW vehicles:
 Driving BMW
 Riding Specialized
 */
}

Builder

Analogy
- There are many ways to build a house, so it may be simpler and will be more flexible piecing the different requirements together rather than trying to find a pre-made house tailored to one’s needs.
When to use it
- When there’s a need for complex objects that can be built step by step (e.g., a text-to-speech [TTS] service may have dozens of options to set the pitch, speed, volume gain, etc. but many settings can be left at their default value).
- This pattern also works well when there are many optional components. In a TTS service, this could mean hooking up the result to post-process the audio, perform a TTS on multiple services at once, etc.
Implementation
- Define a Product class, which must have the common construction steps among all available products.
- There must be a Builder interface to define the methods used to construct the objects.
- Concrete builders are needed to implement the Builder interface in different ways (e.g., a wall builder for a wooden cabin vs. a brick house).
- There can be an optional Director class, which makes it easier to use to builders (e.g., for houses, there could be a MakeCabin method to call the appropriate builders in order to get the expected result, which is done in a single call to the Director instead of possibly chaining many invocations of a concrete builder).
- To use it, the client creates a Builder, passes the Builder to the Director to construct the product and the product is obtained from the Builder (e.g., Builder.getResult).
Pros
- It is flexible.
- It is reusable.
- It encapsulates complex construction logic inside the Builder.
Cons
- For simpler objects, it can make the code unnecessarily convoluted.
- Can be a bit painful to work with if many different products need to be created and used all at once.
Relation to other patterns
- Factory Method and Abstract Factory are simpler and create objects in a single step. The Builder is more complex but allows more control over the construction process.
- While Builder builds a complex object one step at a time, Prototype clones objects.

 go
 
 
 
package main

import "fmt"

// Candy is the Product
type Candy struct {
 Sugar int
 Flavor string
 Color string
 Packaging string
}

// CandyBuilder is the abstract Builder interface
type CandyBuilder interface {
 SetSugar(sugar int) CandyBuilder
 SetFlavor(flavor string) CandyBuilder
 SetColor(color string) CandyBuilder
 SetPackaging(packaging string) CandyBuilder
 Build() Candy
}

// SimpleCandyBuilder is a Concrete Builder
type SimpleCandyBuilder struct {
 candy Candy
}

func NewSimpleCandyBuilder() *SimpleCandyBuilder {
 return &SimpleCandyBuilder{candy: Candy{}}
}

func (b *SimpleCandyBuilder) SetSugar(sugar int) CandyBuilder {
 b.candy.Sugar = sugar
 return b
}

func (b *SimpleCandyBuilder) SetFlavor(flavor string) CandyBuilder {
 b.candy.Flavor = flavor
 return b
}

func (b *SimpleCandyBuilder) SetColor(color string) CandyBuilder {
 b.candy.Color = color
 return b
}

func (b *SimpleCandyBuilder) SetPackaging(packaging string) CandyBuilder {
 b.candy.Packaging = packaging
 return b
}

func (b *SimpleCandyBuilder) Build() Candy {
 return b.candy
}

type CandyDirector struct {
 builder CandyBuilder
}

func NewCandyDirector(builder CandyBuilder) *CandyDirector {
 return &CandyDirector{
 builder: builder,
 }
}

// ConstructPeppermintCandy creates a peppermint candy with green packaging.
func (d *CandyDirector) ConstructPeppermintCandy() Candy {
 return d.builder.SetSugar(10).
 SetFlavor("Peppermint").
 SetColor("White").
 SetPackaging("Green").
 Build()
}

// ConstructCaramelCandy creates a caramel candy with yellow packaging.
func (d *CandyDirector) ConstructCaramelCandy() Candy {
 return d.builder.SetSugar(15).
 SetFlavor("Caramel").
 SetColor("Brown").
 SetPackaging("Yellow").
 Build()
}

func main() {
 builder := NewSimpleCandyBuilder()
 director := NewCandyDirector(builder)

 peppermintCandy := director.ConstructPeppermintCandy()
 fmt.Printf("Peppermint Candy: %+v\n", peppermintCandy)

 caramelCandy := director.ConstructCaramelCandy()
 fmt.Printf("Caramel Candy: %+v\n", caramelCandy)

 // Output:
 // Peppermint Candy: {Sugar:10 Flavor:Peppermint Color:White Packaging:Green}
 // Caramel Candy: {Sugar:15 Flavor:Caramel Color:Brown Packaging:Yellow}
}

Prototype (clone)

Analogy
- Copying genetic information from one cell to another is very complex, while mitotic cell division is efficient and effective.
When to use it
- To create new objects by copying an existing object (the prototype).
- New instantiation of a complex object may be inconvenient.
Implementation
- Define an interface with a clone method.
- Implement the prototype interface in classes that need to be cloned.
- Use the clone method to create new objects.
Pros
- Cloning can be more efficient than creating new instances, especially if instantiation is resource-intensive.
- Cloning allows for dynamic creation and composition of instances at runtime, which brings greater flexibility.
- Prototypes can be managed and modified at runtime, which makes them dynamic.
Cons
- Deep cloning complex objects with intricate references can be challenging.
- It’s not always clear how cloning should behave for each object, especially in complex class hierarchies.
- Cloning can lead to unexpected issues, such as shared references, if not handled correctly.
Relation to other patterns
- Factory Method uses a single method to create new objects, Prototype does it through cloning.
- Abstract Factory and Builder can be combined with Prototype when complex objects are required to be built or cloned.
- Prototypes are often at odds with Singletons, as the Prototype pattern involves creating new object instances.

 go
 
 
 
package main

import "fmt"

// Animal is the prototype interface that all animals must implement
type Animal interface {
 Clone() Animal
 GetInfo() string
}

// Sheep is a concrete prototype that implements the Animal interface
type Sheep struct {
 Name string
 Age int
}

// Clone creates a new Sheep instance with the same data
func (s *Sheep) Clone() Animal {
 // Create a new Sheep instance with the same data
 return &Sheep{Name: s.Name, Age: s.Age}
}

// GetInfo returns the sheep's name and age
func (s *Sheep) GetInfo() string {
 return fmt.Sprintf("Sheep Name: %s, Age: %d", s.Name, s.Age)
}

// Dog is another concrete prototype that implements the Animal interface
type Dog struct {
 Name string
 Breed string
}

// Clone creates a new Dog instance with the same data
func (d *Dog) Clone() Animal {
 return &Dog{Name: d.Name, Breed: d.Breed}
}

// GetInfo returns the dog's name and breed
func (d *Dog) GetInfo() string {
 return fmt.Sprintf("Dog Name: %s, Breed: %s", d.Name, d.Breed)
}

type PrototypeRegistry struct {
 items map[string]Animal
}

func NewPrototypeRegistry() *PrototypeRegistry {
 return &PrototypeRegistry{items: make(map[string]Animal)}
}

func (r *PrototypeRegistry) Register(name string, animal Animal) {
 r.items[name] = animal
}

func (r *PrototypeRegistry) Clone(name string) (Animal, error) {
 if animal, exists := r.items[name]; exists {
 return animal.Clone(), nil
 }
 return nil, fmt.Errorf("prototype not found: %s", name)
}

func main() {
 registry := NewPrototypeRegistry()
 registry.Register("sheep", &Sheep{Name: "Dolly", Age: 4})
 registry.Register("dog", &Dog{Name: "Fido", Breed: "Bulldog"})

 clonedAnimal, err := registry.Clone("sheep")
 if err != nil {
 fmt.Println("Error cloning sheep:", err)
 return
 }

 clonedSheep, ok := clonedAnimal.(*Sheep)
 if !ok {
 fmt.Println("Type assertion failed: not a *Sheep")
 return
 }
 clonedSheep.Name = "Molly"
 fmt.Println(clonedSheep.GetInfo())

 clonedAnimal2, err := registry.Clone("dog")
 if err != nil {
 fmt.Println("Error cloning dog:", err)
 return
 }

 clonedDog, ok := clonedAnimal2.(*Dog)
 if !ok {
 fmt.Println("Type assertion failed: not a *Dog")
 return
 }
 clonedDog.Name = "Rex"
 fmt.Println(clonedDog.GetInfo())

 // Output:
 /*
 Sheep Name: Molly, Age: 4
 Dog Name: Rex, Breed: Bulldog
 */
}

Singleton

Analogy
- The government of a country is (ideally…) a singleton. There is a single group recognized to act as the Government class.
When to use it
- It does two things (not a single responsibility…):
  - It ensures that a class has only one instance;
  - It provides a global point of access to that instance.
- It is often used to manage shared resources, such as a database connection.
Implementation
- A private variable in the package holds the instance.
- Ensure safe access in concurrent environments (e.g., using sync.Once).
- A public function provides global access to the instance.
Pros
- Provides controlled access to a unique instance.
- Instance is created only when needed (lazy Initialization).
- Easily accessible throughout the application (global access).
Cons
- It can introduce a global state in the application, which is generally discouraged in software design.
- Singleton can make unit testing tricky due to its global state.
- It needs careful handling in a concurrent environment to avoid multiple instantiations.
Relation to other patterns
- Singleton can be combined with Factory Method. The factory method ensures that a single instance is created and returned.
- Abstract Factory, Builder, Prototype: these patterns are about creating complex objects, which is a different focus from Singleton’s objective of a single instance.

 go
 
 
 
package main

import (
 "fmt"
 "sync"
)

type ConfigurationData struct {
 DatabaseURL string
}

// ConfigurationManager is a singleton that holds the configuration for the application.
type ConfigurationManager struct {
 config *ConfigurationData
}

var (
 instance *ConfigurationManager
 once sync.Once
)

// GetInstance returns the singleton instance of the ConfigurationManager.
func GetInstance() *ConfigurationManager {
 once.Do(func() {
 instance = &ConfigurationManager{
 config: &ConfigurationData{
 DatabaseURL: "localhost:4321", // Default value
 },
 }
 })
 return instance
}

// UpdateConfig updates configuration if needed
func (m *ConfigurationManager) UpdateConfig(newConfig *ConfigurationData) {
 m.config = newConfig
}

func main() {
 config1 := GetInstance()
 config2 := GetInstance()

 fmt.Println(config1 == config2) // true
}

Structural Design Patterns

These patterns focus on ways to compose objects to form larger structures efficiently and flexibly.

Adapter

Analogy
- An adapter may be needed when traveling abroad to charge devices. While it doesn’t change the device’s functionality, it allows it to work in situations where it would normally be incompatible.
When to use it
- To allow two incompatible interfaces to work together.
- Use an existing class that has an incompatible interface with the rest of the code.
Implementation
- Implement a client interface.
- An adaptee is a class with an incompatible interface (the one that gets adapted).
- An adapter is a class that implements the client interface, translating calls to the adaptee’s interface (the one that adapts the incompatible code).
Pros
- Allows otherwise incompatible interfaces to work together.
- Enables the reuse of existing classes without altering their code.
- Introduces only a small amount of extra code to bridge the compatibility gap.
Cons
- Can add complexity to the code, especially if there are many adaptions.
- The adapter pattern involves an extra layer of abstraction, which can complicate the code and increase overhead.
Relation to other patterns
- While Adapter is used to change an interface, Decorator is used to add responsibilities to objects without modifying their interface.
- The Bridge pattern separates an object’s interface from its implementation so the two can vary independently. Adapter is meant to change the interface of an existing object.
- A Façade provides a simplified interface to a complex subsystem, not necessarily designed for incompatible interfaces, unlike Adapter.

 go
 
 
 
package main

import "fmt"

type Outlet interface {
 InsertInOutlet() string
}

type Pluggable interface {
 InsertInUSOutlet() string
}

type USPlug struct{}

type USPlugAdapter struct {
 usPlug Pluggable
}

func (plug *USPlug) InsertInUSOutlet() string {
 return "Inserted in US Outlet"
}

func NewUSPlugAdapter(usPlug Pluggable) *USPlugAdapter {
 return &USPlugAdapter{usPlug: usPlug}
}

func (adapter *USPlugAdapter) InsertInOutlet() string {
 return adapter.usPlug.InsertInUSOutlet() + ", adapted to fit an Outlet"
}

func ChargeDevice(outlet Outlet) string {
 return outlet.InsertInOutlet()
}

func main() {
 usPlug := &USPlug{}
 adaptedPlug := NewUSPlugAdapter(usPlug)

 result := ChargeDevice(adaptedPlug)
 fmt.Println(result) // Inserted in US Outlet, adapted to fit an Outlet
}

Bridge

Analogy
- A universal remote control bridges the functionality gap between different devices (e.g., it can turn up or down the volume on all devices) with a common interface.
When to use it
- Use it to separate the abstraction (high-level logic) from the implementation (low-level logic), allowing them to be developed independently.
- When you want to avoid a permanent binding between the abstraction and its implementation, particularly when they both may vary frequently.
Implementation
- The abstraction interface/class is a higher-level control layer that delegates the work to the implementation layer.
- The implementor interface defines the interface for the implementation classes.
- Concrete implementations are classes that provide specific implementations of the implementor interface.
- An optional refined abstraction can be used to extend the abstraction to provide more control.
Pros
- Abstractions and implementations can be extended independently.
- Separates high-level and low-level logic into different classes.
- The abstraction and its implementation can be developed and maintained separately.
Cons
- Can increase complexity due to the introduction of additional layers.
- More effort is needed to set up the structure, which might not be necessary for simpler cases.
Relation to other patterns
- The Bridge pattern is often compared to the Adapter pattern. Bridge is designed to separate an interface from its implementation, while Adapter is meant to make unrelated classes work together.
- Bridge is often used in a similar way to Strategy. Strategy typically encapsulates algorithms: Bridge separates an interface from its implementation.
- Abstract Factory can work with Bridge as it can create instances of different classes that implement the abstract interface.
- Builder can be combined with Bridge: builders are the implementations and the director is the abstraction.

 go
 
 
 
package main

import "fmt"

// The Device interface (the abstraction) defines the operations that all
// concrete device implementations must support.
type Device interface {
 TurnOn()
 TurnOff()
 IsEnabled() bool
 SetVolume(volume int)
 GetVolume() int
}

// TV and Radio are concrete implementations of the Device interface.
type TV struct {
 isEnabled bool
}

func (t *TV) TurnOn() {
 t.isEnabled = true
}

func (t *TV) TurnOff() {
 t.isEnabled = false
}

func (t *TV) IsEnabled() bool {
 return t.isEnabled
}

// SetVolume for TV
func (t *TV) SetVolume(volume int) {
 fmt.Printf("TV volume set to %d\n", volume)
}

// GetVolume for TV
func (t *TV) GetVolume() int {
 return 50 // Placeholder
}

type Radio struct {
 isEnabled bool
}

func (r *Radio) TurnOn() {
 r.isEnabled = true
}

func (r *Radio) TurnOff() {
 r.isEnabled = false
}

func (r *Radio) IsEnabled() bool {
 return r.isEnabled
}

// SetVolume for Radio
func (r *Radio) SetVolume(volume int) {
 fmt.Printf("🔉 Radio volume set to %d\n", volume)
}

// GetVolume for Radio
func (r *Radio) GetVolume() int {
 return 30 // Placeholder
}

type RemoteControl struct {
 device Device
 name string
}

func NewRemoteControl(device Device, name string) *RemoteControl {
 fmt.Println("NewRemoteControl", name)
 return &RemoteControl{device: device, name: name}
}

func (r *RemoteControl) TogglePower() {
 if r.device.IsEnabled() {
 fmt.Println(r.name, "🔴 turning off")
 r.device.TurnOff()
 } else {
 fmt.Println(r.name, "🟢 turning on")
 r.device.TurnOn()
 }
}

type AdvancedRemoteControl struct {
 *RemoteControl // Embedding RemoteControl to inherit its methods
}

func NewAdvancedRemoteControl(device Device, name string) *AdvancedRemoteControl {
 return &AdvancedRemoteControl{RemoteControl: NewRemoteControl(device, name)}
}

func (a *AdvancedRemoteControl) SetDeviceVolume(volume int) {
 a.device.SetVolume(volume)
}

func NewTV() *TV {
 return &TV{isEnabled: false}
}

func NewRadio() *Radio {
 return &Radio{isEnabled: false}
}

func main() {
 // TV without advanced remote
 tv := NewTV()
 remote := NewRemoteControl(tv, "Samsung TV")
 remote.TogglePower() // Turns TV on
 remote.TogglePower() // Turns TV off

 // Radio with advanced remote
 radio := NewRadio()
 radioRemote := NewAdvancedRemoteControl(radio, "Sony Radio")
 radioRemote.TogglePower()
 radioRemote.SetDeviceVolume(30)
 radioRemote.TogglePower()

 // Output:
 /*
 NewRemoteControl Samsung TV
 Samsung TV turning on
 Samsung TV turning off
 NewRemoteControl Sony Radio
 Sony Radio turning on
 Radio volume set to 30
 Sony Radio set volume to 30
 Sony Radio turning off
 */
}

Composite (object tree)

Analogy
- The military is a tree structure where orders come from the top, are passed down the divisions, brigades and so on where the leaves are the actual soldiers.
When to use it
- When you want to work with a tree structure and have to perform operations on both individual elements and groups of elements in the same way.
Implementation
- There is a component interface for individual objects and their compositions which defines operations that can be performed on both.
- A leaf represents individual objects in the structure.
- A composite represents a composite of objects (a group of Leaf objects) and implements the component interface.
Pros
- Makes it easier to work with complex tree structures by allowing you to treat individual objects and compositions uniformly.
- Can add and remove new types of components without changing existing code.
- Client code can treat composite structures and individual objects uniformly.
Cons
- Components that do not have much in common end up being overgeneralized.
- The implementation can become overly complex if the hierarchy gets too deep or if extensive functionality is required.
Relation to other patterns
- Builder can be used with Composite because its construction steps can be recursive.
- Chain of Responsibility passes a request along a chain of objects until one of them handles it, Composite arranges objects in a tree structure and works with these structures collectively.
- Iterators can be used to traverse a Composite tree.
- Visitor can be used to execute an operation on a whole tree.
- Shared leaves from the Composite tree can be implemented with Flyweights to reduce RAM usage.
- Decorator only has one component and augments it by wrapping it with new functionality while Composite just runs the logic on all child components.

 go
 
 
 
package main

import (
 "fmt"
 "strings"
)

// Command is the component interface that all commands must implement.
type Command interface {
 Execute()
 Undo()
}

type Document struct {
 content string
}

// WriteCommand is a leaf that implements the Command component interface.
type WriteCommand struct {
 document *Document
 addition string
}

// SaveCommand is another leaf.
type SaveCommand struct {
 document *Document
}

func (w *WriteCommand) Execute() {
 w.document.content += w.addition
 fmt.Printf("Document after writing: %s\n", w.document.content)
}

func (w *WriteCommand) Undo() {
 fmt.Printf("Undo writing: %s\n", w.addition)
 w.document.content = strings.TrimSuffix(w.document.content, w.addition)
}

func (s *SaveCommand) Execute() {
 fmt.Printf("Document saved: %s\n", s.document.content)
}

func (s *SaveCommand) Undo() {
 fmt.Println("Restore to the last saved point...")
}

type CommandManager struct {
 history []Command
}

func (m *CommandManager) ExecuteCommand(cmd Command) {
 cmd.Execute()
 m.history = append(m.history, cmd)
}

func (m *CommandManager) Undo() {
 if len(m.history) == 0 {
 return
 }
 cmd := m.history[len(m.history)-1]
 cmd.Undo()
 m.history = m.history[:len(m.history)-1]
}

// CompositeCommand is a composite that implements the Command component interface.
type CompositeCommand struct {
 commands []Command
}

func (c *CompositeCommand) Execute() {
 for _, cmd := range c.commands {
 cmd.Execute()
 }
}

func (c *CompositeCommand) Undo() {
 for i := len(c.commands) - 1; i >= 0; i-- {
 c.commands[i].Undo()
 }
}

func (c *CompositeCommand) AddCommand(cmd Command) {
 c.commands = append(c.commands, cmd)
}

func main() {
 doc := &Document{}
 write1 := &WriteCommand{document: doc, addition: "Hello "}
 write2 := &WriteCommand{document: doc, addition: "World"}
 save := &SaveCommand{document: doc}

 compositeCommand := &CompositeCommand{}
 compositeCommand.AddCommand(write1)
 compositeCommand.AddCommand(write2)
 compositeCommand.AddCommand(save)

 commandManager := &CommandManager{}
 commandManager.ExecuteCommand(compositeCommand)

 fmt.Println("\nUndoing Composite Command:")
 commandManager.Undo()

 fmt.Printf("\nFinal Document Content: %s\n", doc.content)

 // Output:
 /*
 Document after writing: Hello
 Document after writing: Hello World
 Document saved: Hello World

 Undoing Composite Command:
 Restore to the last saved point...
 Undo writing: World
 Undo writing: Hello

 Final Document Content:
 */
}

Decorator (wrapper)

Analogy
- Wearing layers of clothes: without clothes, it’s cold; with a jacket, it’s warmer; with a raincoat on top, it’s warmer and dryer. The same person is “decorated” to be comfortable under different circumstances.
When to use it
- Used to add new functionality to an object dynamically, without altering its structure.
- Allows for extending an object’s behavior by wrapping it with additional functionality.
Implementation
- The Component interface defines the interface for objects that can have responsibilities added to them dynamically (e.g., a file with read() and write() methods).
- The Concrete component is an object to which additional responsibilities can be attached (e.g., a file with write() could first be compressed or encrypted).
- Decorator classes are wrappers that add responsibilities to the component. They implement the same interface as the component they decorate (e.g., taking the File object, there could be EncryptionDecorator and CompressionDecorator).
Pros
- Provides a flexible alternative to subclassing for extending functionality.
- Responsibilities can be added and removed at runtime.
- Allows for the combination of behaviors by stacking decorators on top of each other.
Cons
- Can lead to complex code structures and debugging difficulties, especially with multiple layers of decorators (order matters!).
- Creating an object decorated with multiple layers can require more complex setup code.
Relation to other patterns
- Unlike Adapter, which changes the behavior of an incompatible class to work with another class, Decorator doesn’t modify the original object and stacks functionality on top of it. Decorator can work recursively, while an Adapter can’t.
- Adapter leads to a wrapped object with a different interface. Proxy maintains the same interface. Decorator enhances it.
- Decorator is similar to Chain of Responsibility. But Decorator maintains consistency throughout the request, while a chain can stop at any point and handle multiple independent operations at once.
- A Decorator is like a Composite but with a single component. Composite also doesn’t add functionality. Prototype can be useful with these two patterns.
- Decorator lets one change the surface level of an object. Strategy lets one change to an entirely different object.

 go
 
 
 
package main

import "fmt"

// Component is the common interface for both the concrete component and the
// decorators. It can have multiple layers of decorators.
type Component interface {
 Operation() string
}

// ConcreteComponent is a concrete component that implements the Component
// interface, defining all the operations that can be altered by decorators.
type ConcreteComponent struct{}

func (c *ConcreteComponent) Operation() string {
 return "ConcreteComponent"
}

// Decorator is a base decorator class. It implements the Component interface
// and has a field for storing a reference to a wrapped object. The default
// implementation of the wrapped object does the actual work, while the
// decorator merely delegates to the wrapped object.
type Decorator struct {
 component Component
}

// Operation Decorator delegates all work to the wrapped component.
func (d *Decorator) Operation() string {
 return d.component.Operation()
}

// ConcreteDecoratorA calls the wrapped object and alter its result in some way.
type ConcreteDecoratorA struct {
 Decorator
}

// Operation Decorators may call parent implementation of the operation, instead of
// calling the wrapped object directly, simplifying extension of decorator classes.
func (d *ConcreteDecoratorA) Operation() string {
 return "ConcreteDecoratorA(" + d.Decorator.Operation() + " + AddedBehaviorA)"
}

func NewConcreteDecoratorA(component Component) *ConcreteDecoratorA {
 return &ConcreteDecoratorA{Decorator{component: component}}
}

type ConcreteDecoratorB struct {
 Decorator
}

func (d *ConcreteDecoratorB) Operation() string {
 pre := "PreBehaviorB | "
 base := d.Decorator.Operation() // Delegate to base Operation
 post := " | PostBehaviorB"
 return pre + "ConcreteDecoratorB(" + base + ")" + post
}

func NewConcreteDecoratorB(component Component) *ConcreteDecoratorB {
 return &ConcreteDecoratorB{Decorator{component: component}}
}

func main() {
 var decoratedComponent Component = &ConcreteComponent{}

 decoratedComponent = NewConcreteDecoratorA(decoratedComponent)
 decoratedComponent = NewConcreteDecoratorB(decoratedComponent)

 fmt.Println(decoratedComponent.Operation())
 // Output:
 // PreBehaviorB | ConcreteDecoratorB(ConcreteDecoratorA(ConcreteComponent + AddedBehaviorA)) | PostBehaviorB
}

Facade

Analogy
- Placing an order by phone is easy (call and get it delivered), but a bunch of operations must happen in the background (warehouse, packaging, suppliers, etc.), which the client has no direct knowledge of.
When to use it
- To provide a simplified interface to a complex subsystem. It doesn’t encapsulate the subsystem but offers an easier or more coherent interface for clients to interact with.
- Useful when dealing with a large body of code, such as a library or a framework.
Implementation
- A Facade interface defines an interface that abstracts the complex functionalities of the subsystem.
- Subsystem classes are the complex parts of the subsystem that the facade will simplify.
- A Facade class implements the facade interface and interacts with the subsystem classes on behalf of the client.
Pros
- Simplifies the interface for complex subsystems, making them easier to use.
- Clients are isolated from the complexities of the subsystem, reducing dependencies and making the system easier to use and maintain.
- Clients can work with a single unified interface instead of a set of complex and potentially confusing interfaces.
Cons
- The facade might limit access to certain features of the subsystem that advanced users might need.
- If not designed carefully, the facade can end up doing too much, becoming overly complex (a “God Object”).
Relation to other patterns
- The Adapter pattern changes the interface of an existing object; the Facade provides a simplified interface to a complex subsystem. The Facade doesn’t wrap the subsystem to change its interface but provides a simpler one.
- The Facade simplifies access to a complex system; the Decorator adds behavior to objects. They are both used to simplify client interactions but achieve this in different ways.
- Often, a Facade is implemented as a Singleton because usually one facade object is enough to manage the underlying systems.
- Abstract Factory can be an alternative when the main goal is to hide the way the subsystem objects are created in the client code.
- Facade makes a single object to represent a whole system while Flyweight makes lots of little objects.

 go
 
 
 
package main

// Example of a facade pattern

import (
 "fmt"
 "strings"
)

// TV is subsystem 1
type TV struct {
 isOn bool
}

func (t *TV) TurnOn() (string, error) {
 if t.isOn {
 return "", fmt.Errorf("❌ TV is already on")
 }
 t.isOn = true
 return "TV is on", nil
}

func (t *TV) TurnOff() (string, error) {
 if !t.isOn {
 return "", fmt.Errorf("❌ TV is already off")
 }
 t.isOn = false
 return "TV is off", nil
}

// SoundSystem is subsystem 2
type SoundSystem struct {
 isOn bool
}

func (s *SoundSystem) TurnOn() (string, error) {
 if s.isOn {
 return "", fmt.Errorf("❌ SoundSystem is already on")
 }
 s.isOn = true
 return "SoundSystem is on", nil
}

func (s *SoundSystem) TurnOff() (string, error) {
 if !s.isOn {
 return "", fmt.Errorf("❌ SoundSystem is already off")
 }
 s.isOn = false
 return "SoundSystem is off", nil
}

// DVDPlayer is subsystem 3
type DVDPlayer struct {
 isOn bool
}

func (d *DVDPlayer) Play() (string, error) {
 if d.isOn {
 return "", fmt.Errorf("❌ DVD is already playing")
 }
 d.isOn = true
 return "DVD is playing", nil
}

func (d *DVDPlayer) Stop() (string, error) {
 if !d.isOn {
 return "", fmt.Errorf("❌ DVD is already stopped")
 }
 d.isOn = false
 return "DVD stopped", nil
}

// HomeTheaterFacade provides a simplified interface to a complex subsystem
type HomeTheaterFacade struct {
 tv *TV
 soundSystem *SoundSystem
 dvdPlayer *DVDPlayer
}

// NewHomeTheaterFacade is a constructor for HomeTheaterFacade
func NewHomeTheaterFacade(tv *TV, soundSystem *SoundSystem, dvdPlayer *DVDPlayer) *HomeTheaterFacade {
 return &HomeTheaterFacade{
 tv: tv,
 soundSystem: soundSystem,
 dvdPlayer: dvdPlayer,
 }
}

// WatchMovie is a facade method
func (h *HomeTheaterFacade) WatchMovie() (string, error) {
 if h.tv == nil || h.soundSystem == nil || h.dvdPlayer == nil {
 return "", fmt.Errorf("❌ home theater is not properly set up")
 }

 response := NewOperationResponse()
 tvResponse, tvErr := h.tv.TurnOn()
 response.AddResponse(tvResponse, tvErr)
 soundSystemResponse, soundSystemErr := h.soundSystem.TurnOn()
 response.AddResponse(soundSystemResponse, soundSystemErr)
 dvdResponse, dvdErr := h.dvdPlayer.Play()
 response.AddResponse(dvdResponse, dvdErr)
 return response.String(), nil
}

// StopMovie is a facade method
func (h *HomeTheaterFacade) StopMovie() string {
 response := NewOperationResponse()
 dvdResponse, dvdErr := h.dvdPlayer.Stop()
 response.AddResponse(dvdResponse, dvdErr)
 soundSystemResponse, soundSystemErr := h.soundSystem.TurnOff()
 response.AddResponse(soundSystemResponse, soundSystemErr)
 tvResponse, tvErr := h.tv.TurnOff()
 response.AddResponse(tvResponse, tvErr)
 return response.String()
}

type OperationResponse struct {
 Responses []string
 Errors []error
}

func NewOperationResponse() *OperationResponse {
 return &OperationResponse{}
}

func (o *OperationResponse) AddResponse(response string, err error) {
 if response != "" {
 o.Responses = append(o.Responses, response)
 }
 if err != nil {
 o.Errors = append(o.Errors, err)
 }
}

func (o *OperationResponse) String() string {
 // Combine all responses and errors into a single string, don't display nil errors
 var responseStrings []string
 responseStrings = append(responseStrings, o.Responses...)
 return strings.Join(responseStrings, "\n")
}

func mapErrorsToStrings(errors []error) []string {
 var errorStrings []string
 for _, err := range errors {
 errorStrings = append(errorStrings, err.Error())
 }
 return errorStrings
}

func main() {
 tv := &TV{}
 soundSystem := &SoundSystem{}
 dvdPlayer := &DVDPlayer{}

 faultyHomeTheater := NewHomeTheaterFacade(tv, soundSystem, nil)
 fmt.Println("Trying to watch a movie with a faulty home theater...")
 faultyMovie, err := faultyHomeTheater.WatchMovie()
 if err != nil {
 fmt.Println(err)
 } else {
 fmt.Println(faultyMovie)
 }

 homeTheater := NewHomeTheaterFacade(tv, soundSystem, dvdPlayer)
 fmt.Println("About to watch a movie with a properly set up home theater...")
 movie, err := homeTheater.WatchMovie()
 if err != nil {
 return
 }
 fmt.Println(movie)

 fmt.Println("Someone tries to turn on the TV while it's already on...")
 _, err = tv.TurnOn()
 if err != nil {
 fmt.Println(err)
 }

 fmt.Println("Trying to start the movie again while it's already playing...")
 watchMovie, err := homeTheater.WatchMovie()
 if err != nil {
 return
 }
 fmt.Println(watchMovie)
 fmt.Println("Stopping the movie...")
 homeTheater.StopMovie()
 fmt.Println("Trying to stop the movie again while it's already stopped...")
 homeTheater.StopMovie()

 // Output:
 /*
 Trying to watch a movie with a faulty home theater...
 ❌ home theater is not properly set up
 About to watch a movie with a properly set up home theater...
 TV is on
 SoundSystem is on
 DVD is playing
 Someone tries to turn on the TV while it's already on...
 ❌ TV is already on
 Trying to start the movie again while it's already playing...
 Stopping the movie...
 Trying to stop the movie again while it's already stopped...
 */
}

Flyweight (cache)

Analogy
- A library (flyweight factory) lends books (flyweight objects with intrinsic state) to library members (context in which extrinsic state exists) without creating a resource nightmare (resources are shared as much as possible).
When to use it
- There’s a need to spawn a huge number of similar objects sharing some context.
- The intrinsic state can be extracted across different objects. E.g., actual trees of the same type may share attributes like texture and color (intrinsic state) but will have distinct attributes like their (x, y, z) position (extrinsic state).
Implementation
- Separate intrinsic and extrinsic states.
  - Get the fields that won’t change (intrinsic state). These are unchanging and unique data points. They are implemented via the Flyweight interface.
  - The extrinsic state is the contextual data that is unique to each object and cannot be shared.
- A concrete flyweight implements the Flyweight interface and stores intrinsic state that can be shared. The extrinsic state is passed as arguments to methods. Fields related to the intrinsic state must be immutable.
- A flyweight factory class can be created to avoid re-creating existing objects with a set comprising the exact same attributes. The intrinsic state is passed to the factory.
Pros
- Can save a lot of memory depending on context. This is only relevant when a very large number of objects are needed.
Cons
- While RAM may decrease, there can be a trade off with CPU as contextual data may need to be recalculated.
- This increases complexity substantially.
Relation to other patterns
- Shared leaf nodes of a Composite tree may be implemented as Flyweights.
- Flyweight creates lots of smaller objects, Facade creates a single large object representing the whole system.

 go
 
 
 
package main

import (
 "fmt"
 "strings"
)

// TextStyle is the flyweight interface
type TextStyle interface {
 ApplyStyle(text string) string
}

// BoldStyle is a concrete flyweight
type BoldStyle struct{}

func (b *BoldStyle) ApplyStyle(text string) string {
 return "**" + text + "**"
}

// UrgentStyle is a concrete flyweight
type UrgentStyle struct{}

func (u *UrgentStyle) ApplyStyle(text string) string {
 return "‼️ " + text + " ‼️"
}

// ItalicStyle is a concrete flyweight
type ItalicStyle struct{}

func (i *ItalicStyle) ApplyStyle(text string) string {
 return "_" + text + "_"
}

// BulletStyle is a concrete flyweight
type BulletStyle struct{}

func (b *BulletStyle) ApplyStyle(text string) string {
 return "* " + text
}

// StyleFactory is the flyweight factory
type StyleFactory struct {
 styles map[string]TextStyle
 compositeStyles map[string]*CompositeStyle // cache for composite styles
}

// NewStyleFactory is the flyweight factory constructor
func NewStyleFactory() *StyleFactory {
 return &StyleFactory{
 styles: make(map[string]TextStyle),
 compositeStyles: make(map[string]*CompositeStyle),
 }
}

func (f *StyleFactory) GetStyle(styleName string) (TextStyle, error) {
 if style, exists := f.styles[styleName]; exists {
 return style, nil
 }

 var style TextStyle
 switch styleName {
 case "bold":
 style = &BoldStyle{}
 case "italic":
 style = &ItalicStyle{}
 case "bullet":
 style = &BulletStyle{}
 default:
 return nil, fmt.Errorf("unknown style: %s", styleName)
 }

 f.styles[styleName] = style
 return style, nil
}

// Extend with the Composite pattern to get multiple styles applied to a text

// CompositeStyle is the composite class
type CompositeStyle struct {
 styles []TextStyle
}

// NewCompositeStyle is the composite constructor
func NewCompositeStyle(styles ...TextStyle) *CompositeStyle {
 return &CompositeStyle{styles: styles}
}

// ApplyStyle is the composite method
func (c *CompositeStyle) ApplyStyle(text string) string {
 for _, style := range c.styles {
 text = style.ApplyStyle(text)
 }
 return text
}

// AddStyle is the composite method
func (c *CompositeStyle) AddStyle(style TextStyle) {
 c.styles = append(c.styles, style)
}

func (f *StyleFactory) GetCompositeStyle(styleNames ...string) TextStyle {
 key := strings.Join(styleNames, "+") // Create a unique key for the combination

 if composite, exists := f.compositeStyles[key]; exists {
 return composite
 }

 var composite = NewCompositeStyle()
 for _, name := range styleNames {
 style, _ := f.GetStyle(name) // Handle error as appropriate
 composite.AddStyle(style)
 }

 f.compositeStyles[key] = composite
 return composite
}

type ConditionalStyle struct {
 condition func(string) bool
 style TextStyle
}

func NewConditionalStyle(condition func(string) bool, style TextStyle) *ConditionalStyle {
 return &ConditionalStyle{condition: condition, style: style}
}

func (c *ConditionalStyle) ApplyStyle(text string) string {
 if c.condition(text) {
 return c.style.ApplyStyle(text)
 }
 return text
}

func main() {
 factory := NewStyleFactory()

 boldStyle, _ := factory.GetStyle("bold")
 fmt.Println(boldStyle.ApplyStyle("Hello"))

 italicStyle, _ := factory.GetStyle("italic")
 fmt.Println(italicStyle.ApplyStyle("Go!"))

 // Reusing flyweights
 anotherBold, _ := factory.GetStyle("bold")
 fmt.Println(anotherBold.ApplyStyle("Flyweight bold"))

 bulletStyle, _ := factory.GetStyle("bullet")
 fmt.Println(bulletStyle.ApplyStyle("Flyweight list"))

 // Composite styles
 italicBulletStyle := factory.GetCompositeStyle("italic", "bullet")
 fmt.Println(italicBulletStyle.ApplyStyle("Italic bullet"))
 bulletItalicStyle := factory.GetCompositeStyle("bullet", "italic")
 fmt.Println(bulletItalicStyle.ApplyStyle("Bullet italic that's incorrect..."))

 // Apply bold style only if the text contains "important"
 importantCondition := func(text string) bool {
 return strings.Contains(text, "important")
 }
 importantBoldStyle := NewConditionalStyle(importantCondition, &BoldStyle{})

 // Apply urgent style to text that contains "urgent"
 urgentCondition := func(text string) bool {
 return strings.Contains(text, "urgent")
 }
 urgentStyle := NewConditionalStyle(urgentCondition, &UrgentStyle{})

 fmt.Println(importantBoldStyle.ApplyStyle("This is important and should be bold"))
 fmt.Println(urgentStyle.ApplyStyle("This is important but not bold"))
 fmt.Println(urgentStyle.ApplyStyle("This is urgent"))
 fmt.Println(importantBoldStyle.ApplyStyle("This is urgent but not emphasized"))

 // Output:
 /*
 **Hello**
 _Go!_
 **Flyweight bold**
 * Flyweight list
 * _Italic bullet_
 _* Bullet italic that's incorrect..._
 **This is important and should be bold**
 This is important but not bold
 ‼️ This is urgent ‼️
 This is urgent but not emphasized
 */
}

Proxy

Analogy
- Cash and credit cards are two ways of handling payment.
When to use it
- For lazy initialization (virtual proxy). A heavy service can be instantiated as needed instead of leaving it running.
- Similarly, for smart referencing (smart reference proxy). This means that if a heavy service needs to be up and running all the time but no clients are using it, it could be shut down until a client connects.
- For access control (protection proxy). For instance, a library implements the Spotify API but needs to limit access to non-paying users. A proxy interface can be used and internal logic can determine which customers can access the API at a given time. The Spotify API remains the same, but custom logic can run before and after its use.
- For logging requests. Instead of just calling an API, the proxy can implement logging and then call the API.
- For caching purposes. Instead of downloading a video over and over again via an API, the result can be cached.
Implementation
- Create a service Proxy interface that is used by the client (Subject interface). The proxy implements the same interface as the service (RealSubject) and can do stuff on top of it (e.g., data caching or logging).
- In most cases, the proxy object does some work and delegates the actual use of the service to the service itself from a field that references that service. The proxy class is instantiated with a reference to the service.
- Optionally, a factory method can be used.
- Also in option, lazy initialization can be implemented for the service object.
Pros
- The proxy transparently controls all aspects of the service and is indistinguishable from the service from the client’s perspective.
- The lifecycle of the service can be managed by the proxy class when appropriate, e.g. to reduce system resources.
- The proxy works even when the actual service could be down.
- New proxies can be added without changing existing code.
Cons
- Complexity increases as new proxies are added.
- It may cause delay in the response from the service if the proxy performs heavy operations.
Relation to other patterns
- Adapter provides a different interface, Proxy provides the same interface and Decorator provides an enhanced version of the interface.
- Proxy is indistinguishable from the original service, whereas Facade may be a simplified interface.
- Decorator is controlled by the client, while Proxy manages the whole lifecycle of the service.

 go
 
 
 
package main

import "fmt"

// RealDocument is the real object that the proxy will represent
type RealDocument struct {
 content string
}

type Displayable interface {
 Display() string
}

type Editable interface {
 Edit(newContent string)
}

// Display is the method that the proxy and the real object both implement, implementing the Displayable interface
func (d *RealDocument) Display() string {
 return "Displaying Document: " + d.content
}

// NewRealDocument is a factory method that creates a new RealDocument
func NewRealDocument(content string) *RealDocument {
 return &RealDocument{content: content}
}

// ProtectedDocument is the proxy object that will control access to the real object
type ProtectedDocument struct {
 content string
 document *RealDocument
 userRole string
}

// Display is the version that the proxy implements
func (p *ProtectedDocument) Display() string {
 fmt.Printf("Access attempt by %s role\n", p.userRole)
 if p.userRole != "admin" {
 fmt.Println("❌ Access Denied: Insufficient permissions")
 return "Access Denied"
 }
 fmt.Println("✅ Document access granted")
 if p.document == nil {
 fmt.Println("⌛ Loading document content...")
 p.document = NewRealDocument(p.content)
 }
 return p.document.Display()
}

// NewProtectedDocument is a factory method that creates a new ProtectedDocument
func NewProtectedDocument(content string, userRole string) *ProtectedDocument {
 return &ProtectedDocument{content: content, userRole: userRole}
}

func ShowDocument(doc Displayable) {
 fmt.Println(doc.Display())
}

func main() {
 doc := NewRealDocument("Top secret stuff.")

 adminProxy := NewProtectedDocument(doc.content, "admin")
 ShowDocument(adminProxy)

 userProxy := NewProtectedDocument(doc.content, "read-only")
 ShowDocument(userProxy)

 // Whoever has access to the real object can bypass the proxy
 fmt.Println("By-passing the proxy:")
 ShowDocument(doc)

 // Output:
 /*
 Access attempt by admin role
 ✅ Document access granted
 ⌛ Loading document content...
 Displaying Document: Top secret stuff.
 Access attempt by read-only role
 ❌ Access Denied: Insufficient permissions
 Access Denied
 By-passing the proxy:
 Displaying Document: Top secret stuff.
 */
}

Behavioral Design Patterns

These patterns deal with algorithms and the assignment of responsibilities between objects.

Chain of Responsibility (CoR, chain of command)

Analogy
- A call center answers with a machine, then a generalist tries to solve the issue, then the engineer comes to the rescue.
When to use it
- When an action must pass a series of checks, such that a handler may process the request or pass it down the chain of handlers.
Implementation
- A Handler interface defines the interface for handling requests and may also have a method to set the next handler of the chain.
- Concrete handlers implement the Handler interface. These either process the request if they can or pass it down the chain until no more handler is available.
- The Client initiates the request to a chain of handlers. The chain can either be pre-defined or the client might do the chaining.
Pros
- Can control the order of request handling.
- Can decouple unrelated operations (single responsibility principle). It decouples the sender from the receiver.
- New handlers can be added without breaking existing code (open/closed principle).
Cons
- Some requests may not be handled if there are no suitable handlers in the chain.
  - When all requests should be handled, a default “catch-all” handler can be implemented to be used at the end of the chain.
  - Another approach could be to disqualify any request that does not match certain criteria if possible, and stop the chain right at the beginning.
- Performance could be an issue if the chain of handlers is lengthy.
Relation to other patterns
- Chain of Responsibility passes a requests in a sequential manner until a handler deals with it.
- It is often used with the Composite pattern, e.g. in a GUI application where clicking on a button inside a dialog, which itself is inside a panel, may produce a chain reaction. This is suitable when the data structure forms a tree.
- The handlers may be implemented as Commands. Or the request itself may arrive as a Command object, where the same operation could be executed in a series of different contexts.
- Like Decorator, this pattern relies on recursive composition. But a Decorator doesn’t stop at any point in the chain and adds behavior on top of an existing object (adds responsibilities) while Chain of Responsibility can execute any operation in any of its handlers (passes responsibility along).

 go
 
 
 
package main

import "fmt"

// BaseLogger is the base struct for all loggers
type BaseLogger struct {
 next Logger
}

// Logger is the interface that all loggers must implement
type Logger interface {
 Log(message string, severity int)
 SetNext(logger Logger)
}

// Different types of log levels
const (
 INFO = 1
 DEBUG = 2
 ERROR = 3
)

func (l *BaseLogger) SetNext(next Logger) {
 l.next = next
}

func (l *BaseLogger) Next(message string, severity int) {
 if l.next != nil {
 l.next.Log(message, severity)
 }
}

type LoggerImpl struct {
 BaseLogger
 levels map[int]bool // Map to hold allowed log levels
}

func NewLogger(levels ...int) *LoggerImpl {
 levelMap := make(map[int]bool)
 for _, level := range levels {
 levelMap[level] = true
 }
 return &LoggerImpl{levels: levelMap}
}

func (l *LoggerImpl) Log(message string, severity int) {
 if l.levels[severity] {
 fmt.Printf("[%s] %s\n", severityToString(severity), message)
 return
 }
 l.Next(message, severity)
}

func severityToString(severity int) string {
 switch severity {
 case INFO:
 return "INFO"
 case DEBUG:
 return "DEBUG"
 case ERROR:
 return "ERROR"
 default:
 return "UNKNOWN"
 }
}

// DefaultLogger is a logger that logs all unhandled messages
type DefaultLogger struct{}

// Log logs the message and severity level for all unhandled messages
func (l *DefaultLogger) Log(message string, severity int) {
 fmt.Printf("[DEFAULT] %s (severity: %d)\n", message, severity)
}

// SetNext does nothing for the default logger
func (l *DefaultLogger) SetNext(next Logger) {
 // default catch-all handler with no next logger
}

func BuildChain(loggers ...Logger) Logger {
 for i := 0; i < len(loggers)-1; i++ {
 loggers[i].SetNext(loggers[i+1])
 }
 return loggers[0] // Return the head of the chain
}

func main() {
 infoLogger := NewLogger(INFO)
 debugLogger := NewLogger(DEBUG)
 errorLogger := NewLogger(ERROR)
 defaultLogger := &DefaultLogger{}

 // Build the chain
 headLogger := BuildChain(debugLogger, infoLogger, errorLogger, defaultLogger)

 // Test the chain
 headLogger.Log("Info message", INFO)
 headLogger.Log("Debug message", DEBUG)
 headLogger.Log("Error message", ERROR)
 headLogger.Log("Unhandled severity message", 0)

 // Output:
 /*
 [INFO] Info message
 [DEBUG] Debug message
 [ERROR] Error message
 [DEFAULT] Unhandled severity message (severity: 0)
 */
}

Command (action, transaction)

Analogy
- A kitchen chef receives a command.
When to use it
- To encapsulate a request as an object, allowing for the parameterization of clients with queues, requests, and operations.
- Support of undoable operations. It turns a request into a stand-alone object that contains all information about the request. This transformation lets one parameterize methods with different requests, delay or queue a request’s execution, and support undoable operations.
Implementation
- Command Interface: This defines a method for executing a command.
- Concrete Command: Implements the command interface and defines the binding between a Receiver object and an action.
- Receiver: Performs the actual work when the command’s Execute method is called.
- Invoker: Asks the command to carry out the request.
- Client: Creates a ConcreteCommand object and sets its receiver.
Pros
- Decouples the classes that invoke the operation from the object that knows how to execute the operation.
- New commands can be added without changing existing code (Open/Closed Principle).
- Multiple commands can be composed into one by using the Composite pattern.
Cons
- Can introduce additional layers of abstraction, which might complicate simpler operations.
- Each new command might require a new concrete class, increasing the number of classes in the system.
Relation to other patterns
- Memento can be used in conjunction with the Command pattern to implement undo/redo functionalities, where Command stores the state of the Receiver.
- Commands can be composed into a Composite command, a macro command that consists of several simpler commands.
- Command encapsulates a request as an object, whereas Strategy encapsulates an algorithm.

 go
 
 
 
package main

import "fmt"

// Command is the command interface: Redo() is implicit
type Command interface {
 Execute()
 Undo()
}

// BankAccount is the receiver
type BankAccount struct {
 Balance float64
 Difference float64
 Operation string
}

// DepositCommand and WithdrawCommand are the concrete commands
type DepositCommand struct {
 account *BankAccount
 amount float64
}

// Execute adds the amount to the account balance
func (d *DepositCommand) Execute() {
 d.account.Balance += d.amount
 d.account.Difference = d.amount
 d.account.Operation = "deposit"
}

type WithdrawCommand struct {
 account *BankAccount
 amount float64
}

// Execute subtracts the amount from the account balance
func (w *WithdrawCommand) Execute() {
 if w.account.Balance >= w.amount {
 w.account.Balance -= w.amount
 w.account.Difference = w.amount
 } else {
 w.account.Difference = 0
 }
 w.account.Operation = "withdrawal"
}

// Undo reverses the DepositCommand operation
func (d *DepositCommand) Undo() {
 d.account.Balance -= d.amount
 d.account.Difference = d.amount
 d.account.Operation = "undo deposit"
}

// Undo reverses the WithdrawCommand operation
func (w *WithdrawCommand) Undo() {
 w.account.Balance += w.amount
 w.account.Difference = w.amount
 w.account.Operation = "undo withdrawal"
}

// CommandManager is the invoker
type CommandManager struct {
 history []Command
 redoStack []Command
}

// ExecuteCommand adds the command to the history and executes it
func (cm *CommandManager) ExecuteCommand(cmd Command) {
 cmd.Execute()
 cm.history = append(cm.history, cmd)
}

// Undo reverses the last command
func (cm *CommandManager) Undo() {
 if len(cm.history) == 0 {
 return
 }
 cmd := cm.history[len(cm.history)-1]
 cmd.Undo()
 cm.history = cm.history[:len(cm.history)-1] // Remove the last command from history
 cm.redoStack = append(cm.redoStack, cmd) // Add it to the redo stack
}

// Redo re-executes the last undone command
func (cm *CommandManager) Redo() {
 if len(cm.redoStack) == 0 {
 return
 }
 cmd := cm.redoStack[len(cm.redoStack)-1]
 cmd.Execute()
 cm.redoStack = cm.redoStack[:len(cm.redoStack)-1] // Remove the last command from redoStack
 cm.history = append(cm.history, cmd) // Add it back to the history
}

// PrintSummary shows the account balance and the difference after the operation
func (b *BankAccount) PrintSummary() {
 if b.Operation == "" {
 fmt.Printf("Account balance: $%.2f\n", b.Balance)
 return
 }

 if b.Operation == "withdrawal" && b.Difference == 0 {
 fmt.Printf("Withdrawal not successful. Account balance: $%.2f\n", b.Balance)
 return
 }

 if b.Operation == "deposit" && b.Difference == 0 {
 fmt.Printf("Deposit not successful. Account balance: $%.2f\n", b.Balance)
 return
 }

 if b.Operation == "withdrawal" {
 fmt.Printf("Account balance after %s: $%.2f ($%.2f - $%.2f)\n", b.Operation, b.Balance, b.Balance+b.Difference, b.Difference)
 return
 }

 if b.Operation == "deposit" {
 fmt.Printf("Account balance after %s: $%.2f ($%.2f + $%.2f)\n", b.Operation, b.Balance, b.Balance-b.Difference, b.Difference)
 return
 }

 if b.Operation == "undo withdrawal" {
 fmt.Printf("Account balance after %s: $%.2f ($%.2f + $%.2f)\n", b.Operation, b.Balance, b.Balance-b.Difference, b.Difference)
 return
 }

 if b.Operation == "undo deposit" {
 fmt.Printf("Account balance after %s: $%.2f ($%.2f - $%.2f)\n", b.Operation, b.Balance, b.Balance+b.Difference, b.Difference)
 return
 }
}

func main() {
 account := &BankAccount{Balance: 100.0}
 manager := CommandManager{}

 deposit := &DepositCommand{account: account, amount: 50}
 withdraw := &WithdrawCommand{account: account, amount: 30}

 account.PrintSummary()

 manager.ExecuteCommand(deposit)
 account.PrintSummary()

 manager.ExecuteCommand(withdraw)
 account.PrintSummary()

 fmt.Println("Undoing the last operation...")
 manager.Undo()
 account.PrintSummary()

 fmt.Println("Redoing the last operation...")
 manager.Redo()
 account.PrintSummary()

 fmt.Println("Undoing the last operation...")
 manager.Undo()
 account.PrintSummary()

 fmt.Println("Undoing the last operation...")
 manager.Undo()
 account.PrintSummary()

 // Output:
 /*
 Account balance: $100.00
 Account balance after deposit: $150.00 ($100.00 + $50.00)
 Account balance after withdrawal: $120.00 ($150.00 - $30.00)
 Undoing the last operation...
 Account balance after undo withdrawal: $150.00 ($120.00 + $30.00)
 Redoing the last operation...
 Account balance after withdrawal: $120.00 ($150.00 - $30.00)
 Undoing the last operation...
 Account balance after undo withdrawal: $150.00 ($120.00 + $30.00)
 Undoing the last operation...
 Account balance after undo deposit: $100.00 ($150.00 - $50.00)
 */
}

Iterator

Analogy
- All roads lead to Rome. There’s more than one way of iterating one’s path through the city.
When to use it
- When there’s a need to provide a way to access a collection of objects in a sequential manner without the need to understand or expose the underlying structure of the collection.
Implementation
- The Iterator Interface defines the operations required for iterating over a collection, such as getNext(), hasNext(), and sometimes remove().
- The Concrete Iterator implements the Iterator Interface and keeps track of the current position in the collection.
- The Aggregate Interface defines the method to create an iterator.
- The Concrete Aggregate implements the Aggregate Interface and returns an instance of the Concrete Iterator.
Pros
- Allows the traversal of elements without exposing the underlying structure (array, tree, graph, etc.).
- Enables multiple simultaneous traversals of a collection.
- Provides a uniform interface for traversing different types of collections.
Cons
- Can increase the complexity of an application by requiring additional classes and interfaces.
- Introduces some overhead to the traversal process, especially if the iterator is feature-rich (like supporting bidirectional traversal).
Relation to other patterns
- Iterators are often used to traverse Composite trees.
- With Factory Method, it can be used to define a method in the Aggregate Interface for creating an iterator.
- An Iterator can use a Memento to capture the state of an iteration.

 go
 
 
 
package main

import (
 "fmt"
 "slices"
 "strconv"
)

// Book struct represents a book in a collection
type Book struct {
 Title string
 Pages int
 Index string // shows the index of the book in the collection
}

// BookIterator defines the interface for iterating over books
type BookIterator interface {
 HasNext() bool
 Next() *Book
 HasPrevious() bool // not always there: could be added
 Previous() *Book // not always there: could be added
 Count() int // The number of books iterated over
 CurrentIndex() int // The current index
 Remove(direction string) error // implement safe removal
 Reset() // Reset the iterator
}

// BookCollection holds a collection of books
type BookCollection struct {
 Books []*Book
}

// Iterator returns a new BookIterator to iterate over the collection
func (bc *BookCollection) Iterator() BookIterator {
 return &BookCollectionIterator{
 bookCollection: bc,
 currentIndex: -1,
 count: 0,
 }
}

// BookCollectionIterator is the concrete iterator for BookCollection
type BookCollectionIterator struct {
 bookCollection *BookCollection
 currentIndex int
 count int // The number of books iterated over
 iterationStarted bool // Flag to indicate if iteration has started
}

// HasNext checks if there is a next book in the collection
func (it *BookCollectionIterator) HasNext() bool {
 if !it.iterationStarted {
 it.currentIndex = -1
 it.iterationStarted = true
 }
 return it.currentIndex+1 < len(it.bookCollection.Books)
}

// HasPrevious checks if there is a previous book in the collection
func (it *BookCollectionIterator) HasPrevious() bool {
 if !it.iterationStarted {
 it.currentIndex = len(it.bookCollection.Books) // Set to length for backward iteration start
 it.iterationStarted = true
 }
 return it.currentIndex-1 >= 0
}

// Next returns the next book in the collection
func (it *BookCollectionIterator) Next() *Book {
 if it.bookCollection == nil || len(it.bookCollection.Books) == 0 {
 fmt.Println("No books in the collection")
 return nil
 }
 if it.HasNext() {
 it.currentIndex++
 it.count++
 return it.bookCollection.Books[it.currentIndex]
 }
 return nil
}

// Previous returns the previous book in the collection
func (it *BookCollectionIterator) Previous() *Book {
 if it.bookCollection == nil || len(it.bookCollection.Books) == 0 {
 fmt.Println("No books in the collection")
 return nil
 }
 if it.currentIndex < 0 {
 it.currentIndex = len(it.bookCollection.Books)
 }
 if it.HasPrevious() {
 it.currentIndex--
 it.count++
 return it.bookCollection.Books[it.currentIndex]
 }
 return nil
}

// Count returns the number of books iterated over
func (it *BookCollectionIterator) Count() int {
 return it.count
}

// CurrentIndex returns the current index
func (it *BookCollectionIterator) CurrentIndex() int {
 return it.currentIndex
}

// Remove safely removes the current element from the collection
func (it *BookCollectionIterator) Remove(direction string) error {
 if it.currentIndex < 0 || it.currentIndex >= len(it.bookCollection.Books) {
 return fmt.Errorf("remove operation out of bounds")
 }

 // Remove the element at currentIndex
 it.bookCollection.Books = slices.Delete(it.bookCollection.Books, it.currentIndex, it.currentIndex+1)

 if direction == "backward" {
 // Stay at the same index after removal
 } else if direction == "forward" {
 // Decrement currentIndex to adjust for the shift in elements after removal
 it.currentIndex--
 } else {
 panic("Invalid direction")
 }
 return nil
}

func (it *BookCollectionIterator) Reset() {
 fmt.Println("Resetting the iterator")
 it.currentIndex = -1
 it.iterationStarted = false
}

func main() {
 collection := &BookCollection{
 Books: []*Book{
 {Title: "The Go Programming Language", Pages: 380, Index: "0"},
 {Title: "Go in Action", Pages: 325, Index: "1"},
 {Title: "Go Design Patterns", Pages: 246, Index: "2"},
 },
 }

 fmt.Println("Book collection:")
 for i, book := range collection.Books {
 index := strconv.Itoa(i + 1)
 fmt.Println(index+".", book.Title, "-", book.Pages, "pages")
 }

 iterator := collection.Iterator()

 fmt.Println("\nIterating forward, removing big books")
 for iterator.HasNext() {
 book := iterator.Next()
 fmt.Println("➡️", "("+book.Index+")", book.Title, "has", book.Pages, "pages, count:", iterator.Count())

 if book.Pages > 350 {
 fmt.Println("‼️", book.Title, "is a large book")
 if err := iterator.Remove("forward"); err != nil {
 fmt.Println("Remove operation failed:", err)
 } else {
 fmt.Println("❌ ", book.Title, "removed")
 }
 }
 }
 iterator.Reset()

 fmt.Println("\nIterating backward, removing small books")
 for iterator.HasPrevious() {
 book := iterator.Previous()
 fmt.Println("⬅️", "("+book.Index+")", book.Title, "still has", book.Pages, "pages, count:", iterator.Count())

 if book.Pages < 250 {
 fmt.Println("‼️", book.Title, "is a small book")
 if err := iterator.Remove("backward"); err != nil {
 fmt.Println("Remove operation failed:", err)
 } else {
 fmt.Println("❌", book.Title, "removed")
 iterator.Next() // Go forward one step, so we don't skip a book
 }
 }
 }
 iterator.Reset()

 fmt.Println("\nIterating forward again")
 for iterator.HasNext() {
 book := iterator.Next()
 fmt.Println("➡️", "("+book.Index+")", book.Title, "has", book.Pages, "pages, count:", iterator.Count())
 }

 fmt.Println("\nIterating forward once again without having reset")
 for iterator.HasNext() {
 book := iterator.Next()
 fmt.Println("➡️", "("+book.Index+")", book.Title, "has", book.Pages, "pages, count:", iterator.Count())
 }
 fmt.Println("\nTotal iteration count:", iterator.Count())

 // Output:
 /*
 Book collection:
 1. The Go Programming Language - 380 pages
 2. Go in Action - 325 pages
 3. Go Design Patterns - 246 pages

 Iterating forward, removing big books
 ➡️ (0) The Go Programming Language has 380 pages, count: 1
 ‼️ The Go Programming Language is a large book
 ❌ The Go Programming Language removed
 ➡️ (1) Go in Action has 325 pages, count: 2
 ➡️ (2) Go Design Patterns has 246 pages, count: 3
 Resetting the iterator

 Iterating backward, removing small books
 ⬅️ (2) Go Design Patterns still has 246 pages, count: 4
 ‼️ Go Design Patterns is a small book
 ❌ Go Design Patterns removed
 ⬅️ (1) Go in Action still has 325 pages, count: 5
 Resetting the iterator

 Iterating forward again
 ➡️ (1) Go in Action has 325 pages, count: 6

 Iterating forward once again without having reset

 Total iteration count: 6
 */
}

Mediator (Intermediary, Controller)

Analogy
- The control tower acts as a mediator for aircraft pilots.
When to use it
- To provide a centralized communication medium between different objects in a system.
- To promote loose coupling by keeping objects from referring to each other explicitly, allowing their interaction to be managed by the Mediator.
- Reduce complexities and dependencies between tightly coupled objects communicating directly.
Implementation
- The Mediator Interface defines the interface for communication that the concrete mediator will implement.
- The Concrete Mediator implements the Mediator Interface and coordinates communication between colleague objects. It knows and maintains its colleagues.
- The Colleague Classes are objects that communicate with each other through the Mediator. Each colleague class knows its mediator object and communicates with it, instead of communicating directly with other colleagues.
Pros
- Allows reducing the coupling between classes of objects by centralizing communication in the Mediator.
- Simplifies maintenance and interaction between classes by having a central point that controls and manages communication.
- Centralizes control over how objects interact, making it easier to understand and manage complex communication networks.
Cons
- The mediator can become overly complex (a “God” object) if too many responsibilities are added.
- Centralizing too much logic and control in the mediator can introduce a single point of failure in the system.
- Finding the right balance in responsibilities between the mediator and its colleagues can be challenging.
Relation to other patterns
- The Mediator pattern can be implemented using the Observer pattern, where the mediator acts as an observer and the colleagues as subjects.
- The Mediator can be seen as a counterpart of the Facade pattern. Facade defines a simplified interface to a subsystem, Mediator centralizes communication between components of the system.
- Mediator can work closely with the Command pattern to orchestrate complex operations involving multiple objects.

 go
 
 
 
package main

import (
 "fmt"
 "math/rand"
)

// Mediator interface defines the method for sending messages between colleagues
type Mediator interface {
 Send(message string, colleague Colleague)
 Subscribe(senderName string, receiver []Colleague)
 Unsubscribe(senderName string, receiver []Colleague)
}

// Colleague interface represents a colleague in the mediator pattern
type Colleague interface {
 Notify(message string)
 Name() string
}

// ConcreteMediator implements the Mediator interface and coordinates communication between colleagues
type ConcreteMediator struct {
 colleagues map[string]Colleague
 subscriptions map[string][]Colleague
}

// RegisterColleague adds colleagues to the mediator's list
func (m *ConcreteMediator) RegisterColleague(name string, colleague Colleague) {
 if m.colleagues == nil {
 m.colleagues = make(map[string]Colleague)
 }
 m.colleagues[name] = colleague
}

// Subscribe adds receiver(s) to the list of subscribers for a particular sender
func (m *ConcreteMediator) Subscribe(senderName string, receiver []Colleague) {
 if m.subscriptions == nil {
 m.subscriptions = make(map[string][]Colleague)
 }
 for _, r := range receiver {
 m.subscriptions[senderName] = append(m.subscriptions[senderName], r)
 }
}

// Unsubscribe removes receiver(s) from the list of subscribers for a particular sender
func (m *ConcreteMediator) Unsubscribe(senderName string, receiver []Colleague) {
 // print the list of receivers about to be removed, converting the receiver slice to a string
 unsub := ""
 for _, r := range receiver {
 unsub += r.Name() + ", "
 }
 unsub = unsub[:len(unsub)-2] // remove the trailing comma and space
 fmt.Println("❌ Unsubscribing", unsub, "from", senderName)

 if m.subscriptions == nil {
 return
 }
 for _, r := range receiver {
 for i, v := range m.subscriptions[senderName] {
 if v == r {
 m.subscriptions[senderName] = append(m.subscriptions[senderName][:i], m.subscriptions[senderName][i+1:]...)
 }
 }
 }
}

// Send sends messages between colleagues, avoiding notifying the sender
func (m *ConcreteMediator) Send(message string, sender Colleague) {
 senderName := sender.Name()
 for _, receiver := range m.subscriptions[senderName] {
 if receiver != sender { // Avoid sending message to self
 receiver.Notify(message)
 }
 }
}

// ComponentAlice is a colleague that can send and receive messages through the mediator
type ComponentAlice struct {
 mediator Mediator
}

// Notify handles messages sent to ComponentAlice
func (c *ComponentAlice) Notify(message string) {
 fmt.Println("👂 Alice heard:", message)
}

// Send sends a message via the mediator
func (c *ComponentAlice) Send(message string) {
 fmt.Println("🔉 Alice talks:", message)
 c.mediator.Send(message, c)
}

func (c *ComponentAlice) Name() string {
 return "Alice"
}

// ComponentBob is another colleague similar to ComponentAlice
type ComponentBob struct {
 mediator Mediator
}

// Notify handles messages sent to ComponentBob
func (c *ComponentBob) Notify(message string) {
 fmt.Println("🦻 Bob heard:", shuffleString(message))
}

// Send sends a message via the mediator
func (c *ComponentBob) Send(message string) {
 fmt.Println("📣 Bob talks:", shuffleString(message))
 c.mediator.Send(message, c)
}

func (c *ComponentBob) Name() string {
 return "Bob"
}

// ComponentCharlie is another colleague similar to ComponentAlice
type ComponentCharlie struct {
 mediator Mediator
}

// Notify handles messages sent to ComponentCharlie
func (c *ComponentCharlie) Notify(message string) {
 fmt.Println("👂 Charlie heard:", message)
}

// Send sends a message via the mediator
func (c *ComponentCharlie) Send(message string) {
 fmt.Println("🔉 Charlie talks:", message)
 c.mediator.Send(message, c)
}

func (c *ComponentCharlie) Name() string {
 return "Charlie"
}

// ComponentDave is another colleague similar to the others
type ComponentDave struct {
 mediator Mediator
}

// Notify handles messages sent to ComponentDave
func (c *ComponentDave) Notify(message string) {
 fmt.Println("👂 Dave heard:", message)
}

// Send sends a message via the mediator
func (c *ComponentDave) Send(message string) {
 fmt.Println("🔉 Dave talks:", message)
 c.mediator.Send(message, c)
}

func (c *ComponentDave) Name() string {
 return "Dave"
}

func shuffleString(s string) string {
 // Convert string to a slice of runes to handle multi-byte characters
 r := []rune(s)

 rand.Shuffle(len(r), func(i, j int) {
 r[i], r[j] = r[j], r[i]
 })

 return string(r)
}

func main() {
 mediator := &ConcreteMediator{}

 alice := &ComponentAlice{mediator}
 bob := &ComponentBob{mediator}
 charlie := &ComponentCharlie{mediator}
 dave := &ComponentDave{mediator}

 mediator.RegisterColleague("Alice", alice)
 mediator.RegisterColleague("Bob", bob)
 mediator.RegisterColleague("Charlie", charlie)
 mediator.RegisterColleague("Dave", dave)

 // Nobody is subscribed to anyone yet, so no messages will be received
 alice.Send("Anyone here?")

 mediator.Subscribe("Alice", []Colleague{bob, charlie, dave}) // Alice sends to them
 mediator.Subscribe("Bob", []Colleague{alice, charlie}) // Bob sends to them
 mediator.Subscribe("Charlie", []Colleague{alice, bob}) // Charlie sends to them
 mediator.Subscribe("Dave", []Colleague{alice}) // Dave sends to Alice

 alice.Send("Hi, I'm Alice!")
 bob.Send("Hi, I'm Bob!")
 charlie.Send("Hi, I'm Charlie!")
 dave.Send("Hi, I'm Dave!")

 mediator.Unsubscribe("Alice", []Colleague{bob, charlie}) // Alice no longer sends to them
 alice.Send("I'm outta here!")

 // Output:
 /*
 🔉 Alice talks: Anyone here?
 🔉 Alice talks: Hi, I'm Alice!
 🦻 Bob heard: ,ciAleI'H mi !
 👂 Charlie heard: Hi, I'm Alice!
 👂 Dave heard: Hi, I'm Alice!
 📣 Bob talks: i B'!bIHmo,
 👂 Alice heard: Hi, I'm Bob!
 👂 Charlie heard: Hi, I'm Bob!
 🔉 Charlie talks: Hi, I'm Charlie!
 👂 Alice heard: Hi, I'm Charlie!
 🦻 Bob heard: ' aiemH !CIli,hr
 🔉 Dave talks: Hi, I'm Dave!
 👂 Alice heard: Hi, I'm Dave!
 ❌ Unsubscribing Bob, Charlie from Alice
 🔉 Alice talks: I'm outta here!
 👂 Dave heard: I'm outta here!
 */
}

Memento (Snapshot)

Analogy
- The “undo” and “redo” buttons of a text editor (save and restore state) or the “rollback” feature of a database.
When to use it
- When there is a need to restore an object back to its previous state (e.g. “undo” or “rollback” operations), without violating encapsulation.
Implementation
- Originator: The object whose state needs to be saved and restored.
- Memento: An object that encapsulates the state of the originator at a particular time, which is usually immutable once constructed.
- Caretaker: An object that keeps track of the mementos but does not operate on or examine the contents of a memento. It is responsible for knowing when and why to save and restore the originator’s state.
- In languages supporting nested classes, the Memento can be nested inside the Originator.
  - This way, the caretaker can’t access the memento directly, and the originator can access the memento’s fields directly.
- In other languages like Go which don’t even have classes, the implementation can be based on an intermediate interface.
  - This makes the fields of the memento struct public.
  - There is another approach to restrict access:
    - Originator Interface: This defines the high-level interface for creating a memento and restoring the Originator’s state from a memento. However, it does not expose internal state details.
    - ConcreteOriginator: Implements the Originator interface and contains the internal state that needs to be saved and restored. It knows how to save its internal state to a Memento and restore it, but these Mementos are opaque to the outside world. In Go, this would be defined in a separate package to restrict access to the internal state.
    - Memento Interface: Provides a very restricted interface that might only allow the Memento to be passed around but not altered or viewed (no getters for the state, for instance). In Go, this would be an empty struct to prevent any access to the internal state.
    - ConcreteMemento: Implements the Memento interface and stores the internal state of the ConcreteOriginator. The ConcreteMemento is typically a private or inner class of the ConcreteOriginator, ensuring that only the ConcreteOriginator can access the internal state stored within the Memento. In Go, this would be a struct with unexported fields and it would be present in the same package as the ConcreteOriginator.
    - Caretaker: Manages the mementos without knowing their content or structure. It can request a Memento from the Originator and store it, and it can pass a Memento back to the Originator for state restoration, but it cannot access the state stored inside the Memento.
Pros
- The internal state of the originator is saved externally without breaking encapsulation.
- The originator doesn’t need to keep versions of its state, simplifying its code.
- It enables the implementation of undo mechanisms in a relatively straightforward manner.
Cons
- It can be resource-intensive if the originator’s state is large or if there are many mementos stored (think of GIMP or Photoshop when working with large images and a growing undo stack!).
- It adds complexity to the code, particularly in managing the lifecycle and permissions of mementos.
- The caretaker must manage the lifetimes of mementos carefully to avoid excessive memory use (hidden implementation costs).
Relation to other patterns
- Memento can be used in conjunction with the Command pattern to store state for undoable commands.
- It can store the state of an Iterator, allowing it to return to a specific point in the iteration.
- Both Memento and Prototype involve creating a copy of an object, but for different purposes: Prototype for creating a duplicate object; Memento for saving state.

 go
 
 
 
package main

import "fmt"

// Memento is a snapshot of the originator's state
type Memento struct {
 state string
}

// Originator is the object whose state needs to be saved
type originator struct {
 state string
}

// setState updates the state of the originator
func (o *originator) setState(state string) {
 o.state = state
}

// saveStateToMemento saves the current state to a memento
func (o *originator) saveStateToMemento() *Memento {
 return &Memento{state: o.state}
}

// restoreStateFromMemento restores the state from a memento
func (o *originator) restoreStateFromMemento(m *Memento) {
 o.state = m.state
}

// Caretaker could also be a single stack with an index to move back and forth
type Caretaker struct {
 undoStack []*Memento
 redoStack []*Memento
}

// saveState saves the current state of the originator to the undoStack of the caretaker
func (c *Caretaker) saveState(o *originator) {
 m := o.saveStateToMemento()
 c.undoStack = append(c.undoStack, m) // Save the current state before changing it
}

// changeState changes the state of the originator and saves the current state to the undoStack of the caretaker
func (c *Caretaker) changeState(o *originator, newState string) {
 c.saveState(o) // Save the current state before making a change
 o.setState(newState)
}

// undo restores the state of the originator to the previous state, if any
func (c *Caretaker) undo(o *originator) {
 if len(c.undoStack) == 0 {
 return
 }

 lastIndex := len(c.undoStack) - 1
 memento := c.undoStack[lastIndex]
 c.undoStack = c.undoStack[:lastIndex] // Pop from undoStack

 c.redoStack = append(c.redoStack, o.saveStateToMemento()) // Save the current state to redoStack before undoing
 o.restoreStateFromMemento(memento)
}

// redo restores the state of the originator to the next state, if any
func (c *Caretaker) redo(o *originator) {
 if len(c.redoStack) == 0 {
 return
 }

 lastIndex := len(c.redoStack) - 1
 memento := c.redoStack[lastIndex]
 c.redoStack = c.redoStack[:lastIndex] // Pop from redoStack

 c.undoStack = append(c.undoStack, o.saveStateToMemento()) // Save the current state to undoStack before redoing
 o.restoreStateFromMemento(memento)
}

func main() {
 originator := &originator{}
 caretaker := &Caretaker{}

 // Initial state is saved
 caretaker.saveState(originator)

 // Changes to the originator are made through the Caretaker to ensure states are saved
 caretaker.changeState(originator, "State #1")
 caretaker.changeState(originator, "State #2")
 caretaker.changeState(originator, "State #3")

 fmt.Println("Current State:", originator.state)

 caretaker.undo(originator)
 fmt.Println("State after undo:", originator.state)

 caretaker.undo(originator)
 fmt.Println("State after second undo:", originator.state)

 caretaker.undo(originator)
 fmt.Println("State after third undo:", originator.state)

 caretaker.redo(originator)
 fmt.Println("State after redo:", originator.state)

 caretaker.redo(originator)
 fmt.Println("State after second redo:", originator.state)

 caretaker.redo(originator)
 fmt.Println("State after third redo:", originator.state)

 caretaker.redo(originator)
 fmt.Println("State after fourth redo:", originator.state)

 caretaker.undo(originator)
 fmt.Println("State after undo:", originator.state)

 // Output:
 /*
 Current State: State #3
 State after undo: State #2
 State after second undo: State #1
 State after third undo:
 State after redo: State #1
 State after second redo: State #2
 State after third redo: State #3
 State after fourth redo: State #3
 State after undo: State #2
 */
}

Observer (Event-Subscriber, Listener)

Analogy
- A newspaper publisher (subject) has a list of subscribers (observers) who want to be notified when a new issue is published.
When to use it
- To create a subscription mechanism that allows multiple objects to listen and react to events happening in another object, known as the subject.
- For implementing distributed event handling systems, in scenarios where an object needs to notify other objects about its state changes without being dependent on them.
Implementation
- Subject Interface (Publisher): Defines the interface for attaching, detaching, and notifying observers. It contains a list of subscribers with methods like subscribe, unsubscribe, and notify.
  - Concrete Subject: Maintains the state of the object and notifies observers when the state changes.
- Observer Interface (Subscriber): Defines the interface for receiving updates from the subject (usually just an update method).
  - Concrete Observers: Implements the observer interface and keeps a reference to the subject so that they can automatically update themselves in response to state changes.
Pros
- The subject doesn’t need to know anything about the observers, other than they implement the Observer interface (loose coupling).
- Subscribers/observers can be managed at runtime by the client.
- Changes in the subject are effectively broadcasted to all interested observers.
Cons
- If there are many observers or if the updates are frequent, the system can become overwhelmed. Besides, the order of updates could be unpredictable.
- Care must be taken to properly manage observer registration and deregistration to avoid memory leaks.
Relation to other patterns
- Observer resembles closely to the Mediator pattern. While it can be used to implement distributed event handling systems, Mediator is more focused on centralizing communication between objects.
- The Observer pattern can use the Singleton pattern to implement a central registry of observers.

 go
 
 
 
package main

import (
 "fmt"
 "strconv"
 "sync"
)

// Subject is implemented implicitly by WeatherData: it's not needed here
type Subject interface {
 RegisterObserver(o Observer)
 RemoveObserver(o Observer)
 NotifyObservers()
}

// WeatherConditions is the data that will be sent to the observers
type WeatherConditions struct {
 Humidity float64
 Pressure float64
 Temperature float64
}

// WeatherData is the subject/publisher that will notify the observers/subscribers
type WeatherData struct {
 observers []Observer
 conditions WeatherConditions
}

// RegisterObserver adds an observer to the list of observers
func (w *WeatherData) RegisterObserver(o Observer) {
 w.observers = append(w.observers, o)
}

// RemoveObserver removes an observer from the list of observers
func (w *WeatherData) RemoveObserver(o Observer) {
 for i, observer := range w.observers {
 if observer == o {
 w.observers = append(w.observers[:i], w.observers[i+1:]...)
 break
 }
 }
}

// NotifyObservers sends the data to all the observers
// Using goroutines, this will notify in random order
func (w *WeatherData) NotifyObservers() {
 var wg sync.WaitGroup
 for _, observer := range w.observers {
 wg.Add(1)
 go func(o Observer) {
 defer wg.Done() // Ensure the WaitGroup counter decrements
 o.Update(w.conditions)
 }(observer)
 }
 wg.Wait()
}

// SetMeasurementsAndNotify sets the weather conditions and notifies the observers
func (w *WeatherData) SetMeasurementsAndNotify(conditions WeatherConditions) {
 w.conditions = conditions
 w.NotifyObservers()
}

// Observer is the interface that observers must implement
type Observer interface {
 Update(conditions WeatherConditions)
}

// CurrentConditionsDisplay is an observer that displays the current conditions
type CurrentConditionsDisplay struct {
 weatherData *WeatherData
}

// NewCurrentConditionsDisplay creates a new CurrentConditionsDisplay and registers it with the WeatherData
func NewCurrentConditionsDisplay(weatherData *WeatherData) *CurrentConditionsDisplay {
 display := &CurrentConditionsDisplay{weatherData: weatherData}
 weatherData.RegisterObserver(display)
 return display
}

// Update is called by the WeatherData when the conditions change
func (c *CurrentConditionsDisplay) Update(conditions WeatherConditions) {
 fmt.Printf("[fancy display] Current conditions: %.2fF degrees, %.2f%% humidity, %.2f pressure\n",
 conditions.Temperature,
 conditions.Humidity,
 conditions.Pressure,
 )
}

// TemperatureDisplay is an observer that displays only the temperature
type TemperatureDisplay struct {
 weatherData *WeatherData
}

// NewTemperatureDisplay creates a new TemperatureDisplay and registers it with the WeatherData
func NewTemperatureDisplay(weatherData *WeatherData) *TemperatureDisplay {
 display := &TemperatureDisplay{weatherData: weatherData}
 weatherData.RegisterObserver(display)
 return display
}

// Update is called by the WeatherData when the conditions change
func (t *TemperatureDisplay) Update(conditions WeatherConditions) {
 fmt.Printf("[simple display] Temperature: %s degrees\n", strconv.FormatFloat(conditions.Temperature, 'f', 0, 32))
}

func main() {
 weatherData := &WeatherData{}

 NewCurrentConditionsDisplay(weatherData)
 NewTemperatureDisplay(weatherData)

 weatherData.SetMeasurementsAndNotify(WeatherConditions{Temperature: 70, Humidity: 65, Pressure: 30.4})
 weatherData.SetMeasurementsAndNotify(WeatherConditions{Temperature: 68, Humidity: 70, Pressure: 29.2})

 // Output:
 /*
 [fancy display] Current conditions: 70.00F degrees, 65.00% humidity, 30.40 pressure
 [simple display] Temperature: 70 degrees
 [simple display] Temperature: 68 degrees
 [fancy display] Current conditions: 68.00F degrees, 70.00% humidity, 29.20 pressure
 */
}

State

Analogy
- A smartphone can be in different states: locked, unlocked, charging, etc. For example, when it’s locked, pressing the home button doesn’t do anything, but when it’s unlocked, pressing it goes to the home screen.
When to use it
- To allow an object to alter its behavior when its internal state changes. This pattern encapsulates state-specific behavior within state objects, making an object’s behavior dependent on its state.
- For implementing finite state machines in a more organized and maintainable way (i.e., refactor large if-else/switch constructs).
- When the number of states is large, and the state-specific behavior changes frequently.
Implementation
- State Interface: Defines a common interface for all concrete state classes, encapsulating the state-specific behavior.
- Concrete State Classes: Implement the State interface and provide the implementation for the state-specific behavior.
- Context Class: Maintains an instance of a ConcreteState subclass that defines the current state and delegates state-specific behavior to the current state object.
Pros
- Single Responsibility Principle: Each state is encapsulated in its own class.
- Open/Closed Principle: It is easy to add new states without changing the context or other states.
- Reduces complex conditional logic in the context by encapsulating state-specific behavior.
Cons
- Can lead to an increase in the number of classes and boilerplate code.
- The context must carefully manage state objects and transitions, which can get complex.
- Overkill for a simple state machine which doesn’t change much.
Relation to other patterns
- While Strategy usually changes the algorithm used by the context (objects being unaware of each other), State changes the behavior of the context based on its internal state.
- State can be used to change the behavior of Commands based on the state of the system.

 go
 
 
 
package main

import (
 "fmt"
 "sync"
 "time"
)

// State is the interface for the vending machine states
type State interface {
 CancelTransaction()
 DispenseItem()
 InsertMoney(amount int)
}

// ReadyState allows item dispensing if there's sufficient balance
type ReadyState struct {
 machine *VendingMachine
}

// InsertMoney adds money to the vending machine balance
func (rs *ReadyState) InsertMoney(amount int) {
 fmt.Printf("🪙 Inserted $%d\n", amount)
 rs.machine.balance += amount
}

// DispenseItem dispenses an item if there's sufficient balance
// and the machine has items in stock
func (rs *ReadyState) DispenseItem() {
 if rs.machine.balance < rs.machine.itemPrice {
 fmt.Println("🚨 Tried to dispense... Insufficient balance!")
 return
 }

 rs.machine.setState(rs.machine.busyDispensingState)
 fmt.Println("🥫 Dispensing $2 item...")

 time.Sleep(1 * time.Second / 5) // Simulate the dispensing process

 rs.machine.balance -= rs.machine.itemPrice
 rs.machine.itemCount--

 fmt.Println("✅ Item dispensed.")

 if rs.machine.balance > 0 {
 fmt.Println("💵 Returning change of $" + fmt.Sprint(rs.machine.balance))
 rs.machine.balance = 0
 }

 if rs.machine.itemCount == 0 {
 fmt.Println("0️⃣ Out of stock!")
 rs.machine.setState(rs.machine.outOfStockState)
 } else {
 rs.machine.setState(rs.machine.readyState)
 }
}

// CancelTransaction does nothing when the machine is ready
// and there's no transaction to cancel, and it refunds the balance
// when there's a pending transaction
func (rs *ReadyState) CancelTransaction() {
 if rs.machine.balance > 0 {
 fmt.Printf("❌ Cancelling transaction, returning $%d\n", rs.machine.balance)
 rs.machine.balance = 0
 return
 }
 fmt.Println("⚠️ No transaction to cancel.")
}

// OutOfStockState prevents item dispensing
type OutOfStockState struct {
 machine *VendingMachine
}

// InsertMoney does nothing when the machine is out of stock
func (oos *OutOfStockState) InsertMoney(amount int) {
 fmt.Println("🔴 Machine out of stock. Money insertion is futile.")
}

// DispenseItem does nothing when the machine is out of stock
func (oos *OutOfStockState) DispenseItem() {
 fmt.Println("🔴 Machine out of stock. Unable to dispense.")
}

// CancelTransaction does nothing when the machine is out of stock
func (oos *OutOfStockState) CancelTransaction() {
 fmt.Println("🔴 Machine out of stock. No transaction to cancel.")
}

// BusyDispensingState prevents further item dispensing and money insertion
type BusyDispensingState struct {
 machine *VendingMachine
}

func (bd *BusyDispensingState) BusyDispensing() {
 fmt.Println("🛑 Dispensing...")
}

// InsertMoney returns the money when the machine is busy dispensing
func (bd *BusyDispensingState) InsertMoney(amount int) {
 fmt.Println("🛑 Busy dispensing. Money insertion is futile.")
}

// DispenseItem does nothing when the machine is busy dispensing
func (bd *BusyDispensingState) DispenseItem() {
 fmt.Println("🛑 Already dispensing, be patient!")
}

// CancelTransaction does nothing when the machine is busy dispensing
func (bd *BusyDispensingState) CancelTransaction() {
 fmt.Println("🛑 Busy dispensing. No transaction to cancel.")
}

// VendingMachine is the context for the state pattern
// in which all states are defined
type VendingMachine struct {
 busyDispensingState State
 readyState State
 outOfStockState State
 currentState State
 itemCount int
 balance int
 itemPrice int
}

// NewVendingMachine creates a new vending machine
func NewVendingMachine(itemCount, itemPrice int) *VendingMachine {
 vm := &VendingMachine{
 itemCount: itemCount,
 itemPrice: itemPrice,
 }
 readyState := &ReadyState{machine: vm}
 outOfStockState := &OutOfStockState{machine: vm}
 busyDispensingState := &BusyDispensingState{machine: vm}

 vm.busyDispensingState = busyDispensingState
 vm.readyState = readyState
 vm.outOfStockState = outOfStockState
 vm.setState(readyState)

 return vm
}

// InsertMoney adds money to the vending machine balance
func (vm *VendingMachine) InsertMoney(amount int) {
 vm.currentState.InsertMoney(amount)
}

// DispenseItem dispenses an item if there's sufficient balance
func (vm *VendingMachine) DispenseItem() {
 vm.currentState.DispenseItem()
 if vm.itemCount == 0 {
 vm.setState(vm.outOfStockState)
 }
}

// setState changes the current state of the vending machine
func (vm *VendingMachine) setState(state State) {
 vm.currentState = state
}

func (vm *VendingMachine) CancelTransaction() {
 fmt.Println("❌ Cancelling transaction...")
 vm.currentState.CancelTransaction()
}

func main() {
 vendingMachine := NewVendingMachine(10, 2) // 10 items, $2 each

 fmt.Println("Buying 3 items...")
 vendingMachine.InsertMoney(2)
 vendingMachine.DispenseItem()
 vendingMachine.InsertMoney(2)
 vendingMachine.DispenseItem()
 vendingMachine.InsertMoney(5)
 vendingMachine.DispenseItem()

 fmt.Println("\nTrying to buy an item with insufficient balance...")
 vendingMachine.InsertMoney(1)
 vendingMachine.DispenseItem() // Fails
 vendingMachine.CancelTransaction()

 fmt.Println("\nBuying 1 item with extra money...")
 vendingMachine.InsertMoney(5)
 vendingMachine.DispenseItem()

 fmt.Println("\nTrying to dispense multiple times in quick succession won't break the machine...")
 vendingMachine.InsertMoney(5)
 var wg sync.WaitGroup
 for i := 0; i < 3; i++ {
 wg.Add(1)
 go func() {
 defer wg.Done()
 vendingMachine.InsertMoney(5)
 vendingMachine.DispenseItem()
 vendingMachine.CancelTransaction()
 }()
 wg.Wait()
 }

 // Output:
 /*
 Buying 3 items...
 🪙 Inserted $2
 🥫 Dispensing $2 item...
 ✅ Item dispensed.
 🪙 Inserted $2
 🥫 Dispensing $2 item...
 ✅ Item dispensed.
 🪙 Inserted $5
 🥫 Dispensing $2 item...
 ✅ Item dispensed.
 💵 Returning change of $3

 Trying to buy an item with insufficient balance...
 🪙 Inserted $1
 🚨 Tried to dispense... Insufficient balance!
 ❌ Cancelling transaction...
 ❌ Cancelling transaction, returning $1

 Buying 1 item with extra money...
 🪙 Inserted $5
 🥫 Dispensing $2 item...
 ✅ Item dispensed.
 💵 Returning change of $3

 Trying to dispense multiple times in quick succession won't break the machine...
 🪙 Inserted $5
 🪙 Inserted $5
 🥫 Dispensing $2 item...
 ✅ Item dispensed.
 💵 Returning change of $8
 ❌ Cancelling transaction...
 ⚠️ No transaction to cancel.
 🪙 Inserted $5
 🥫 Dispensing $2 item...
 ✅ Item dispensed.
 💵 Returning change of $3
 ❌ Cancelling transaction...
 ⚠️ No transaction to cancel.
 🪙 Inserted $5
 🥫 Dispensing $2 item...
 ✅ Item dispensed.
 💵 Returning change of $3
 ❌ Cancelling transaction...
 ⚠️ No transaction to cancel.
 */
}

Strategy

Analogy
- Choosing a transportation method in Google Maps: walking; driving; cycling or public transport. Each method is a strategy selected via a button in the UI. The goal is to reach a given destination, but the method of transportation can vary, and so will the algorithm calculating the route.
When to use it
- To define a family of algorithms, encapsulate each one, and make them interchangeable (e.g., different text parsers classes implementing the same methods but providing different results).
- Strategy lets the algorithm vary independently from clients that use it.
- When there are multiple ways of doing something and there’s a need to switch between these methods easily at runtime.
Implementation
- Strategy Interface: This defines a common interface for all concrete strategies to implement.
- Concrete Strategies: Implement the Strategy Interface with specific algorithmic implementations.
- Context Class: Maintains a reference to a strategy object and delegates it the responsibility of executing the algorithm. The context is configured with a ConcreteStrategy object and may define an interface that lets the strategy access its data.
Pros
- Allows dynamically changing the behavior of an object.
- Encapsulates algorithm implementations from the core business logic.
- Promotes the reuse of individual strategies across different contexts.
Cons
- Introduces multiple classes and interfaces, which increases complexity.
- Clients must understand how strategies differ (and be aware of their existence) to select the appropriate one.
Relation to other patterns
- Factory Method is often used with Strategy to instantiate the appropriate ConcreteStrategy.
- State has a similar structure to Strategy. While Strategy changes the behavior of a context, State’s behavior change is more intrinsic to the context’s state.
- Command can be seen as a specialization of Strategy, with the strategy being parameterized with actions to execute.

 go
 
 
 
package main

import "fmt"

// Formatter is the strategy interface
type Formatter interface {
 Format(text string) string
}

// MarkdownFormatter formats text with Markdown syntax
type MarkdownFormatter struct{}

// Format formats text with Markdown syntax
func (m *MarkdownFormatter) Format(text string) string {
 return fmt.Sprintf("**%s**", text)
}

// HTMLFormatter formats text with HTML tags
type HTMLFormatter struct{}

// Format formats text with HTML tags
func (h *HTMLFormatter) Format(text string) string {
 return fmt.Sprintf("<strong>%s</strong>", text)
}

// CustomFormatter formats text with custom syntax
type CustomFormatter struct{}

// Format formats text with custom syntax
func (c *CustomFormatter) Format(text string) string {
 return fmt.Sprintf("[[[ %s ]]]", text)
}

// TextEditor is the context inside which the strategy is used
type TextEditor struct {
 formatter Formatter
}

// SetFormatter sets the formatter
func (t *TextEditor) SetFormatter(formatter Formatter) {
 t.formatter = formatter
}

// PublishText publishes the text using the selected formatter
func (t *TextEditor) PublishText(text string) {
 fmt.Println(t.formatter.Format(text))
}

func main() {
 editor := &TextEditor{}

 // Using Markdown formatter
 markdownFormatter := &MarkdownFormatter{}
 editor.SetFormatter(markdownFormatter)
 editor.PublishText("Choosing the Markdown strategy")

 // Switching to HTML formatter
 htmlFormatter := &HTMLFormatter{}
 editor.SetFormatter(htmlFormatter)
 editor.PublishText("Choosing the HTML strategy")

 // Switching to Custom formatter
 customFormatter := &CustomFormatter{}
 editor.SetFormatter(customFormatter)
 editor.PublishText("Choosing the Custom strategy")

 // Output:
 /*
 **Choosing the Markdown strategy**
 <strong>Choosing the HTML strategy</strong>
 [[[ Choosing the Custom strategy ]]]
 */
}

Template method

Analogy
- A recipe for baking a cake: the steps are roughly the same for all cakes, but the ingredients and some steps can vary.
When to use it
- To define the skeleton of an algorithm in the superclass while letting subclasses override specific steps of the algorithm without changing its structure.
- When multiple subclasses should implement a similar algorithm with some slight differences in certain steps. Hooks can be used to provide optional parts of the algorithm that subclasses might or might not override.
Implementation
- Abstract Class / Interface with Template Method: Defines the template method, which is a method that outlines the algorithm’s steps, some of which can be default implementations (concrete methods) or abstract methods (hooks) that subclasses will override.
- Concrete Class: Implements the abstract methods (hooks) defined in the abstract class, thereby providing specific behavior for the steps that vary between different subclasses.
Pros
- Promotes reusing code by extracting common behavior into a superclass.
- Subclasses can override certain steps of the algorithm without changing its structure.
- The superclass can control the algorithm’s structure while allowing subclass-specific behavior.
Cons
- Requires inheritance. This is not a problem in languages like Java, but it can be a limitation in languages that don’t have classes, such as Go.
- Subclasses can only change certain parts of the algorithm, not the overall structure or order of steps.
Relation to other patterns
- Both Template Method and Strategy can encapsulate algorithms. The key difference is that Strategy uses composition to change parts of the algorithm, while Template Method uses inheritance.
- Factory Method is often used as a step in a Template Method, particularly when creating objects that need to vary by subclass.

 go
 
 
 
package main

import "fmt"

type GameAI interface {
 TakeTurn()
 CollectResources()
 BuildStructures()
 BuildUnits()
 Attack()
}

// BaseAI provides default implementations for some methods and leaves others as hooks.
type BaseAI struct {
 GameAI // Embedding the interface for polymorphism
}

func (ai *BaseAI) TakeTurn() {
 ai.CollectResources()
 ai.BuildStructures()
 ai.BuildUnits()
 ai.Attack()
}

func (ai *BaseAI) CollectResources() {
 fmt.Println("Collecting resources...")
}

func (ai *BaseAI) BuildStructures() {
 // Default implementation: Do nothing.
 // This acts as a hook method that can be overridden.
}

func (ai *BaseAI) BuildUnits() {
 // Hook method
}

type WolfAI struct {
 BaseAI
}

func (orc *WolfAI) BuildStructures() {
 fmt.Println("Building Wolf structures...")
}

func (orc *WolfAI) Attack() {
 fmt.Println("Wolves attacking!")
}

func (orc *WolfAI) BuildUnits() {
 fmt.Println("Training Wolf units...")
}

func main() {
 wolfAI := &WolfAI{}
 wolfAI.BaseAI.GameAI = wolfAI // Link for polymorphism

 wolfAI.TakeTurn() // Executes the algorithm, with some steps overridden by WolfAI

 // Output:
 /*
 Collecting resources...
 Wolves attacking!
 */
}

Visitor

Analogy
- A tax auditor visiting different businesses to calculate their taxes.
When to use it
- To separate algorithms from the objects on which they operate, allowing for new operations to be added to these objects without modifying their classes.
- When dealing with a fixed set of object structures but needing to extend their functionality dynamically.
Implementation
- Element Interface: Defines an Accept method that takes a visitor and allows the visitor to perform some operation on the element.
- Concrete Element Classes: Implement the Element Interface and define the Accept method. The Accept method calls the visitor’s method that’s designed to handle the element.
- Visitor Interface: Defines a method for each type of concrete element in the object structure that the visitor can operate on.
- Concrete Visitor Classes: Implement the Visitor interface, providing the implementation for each operation on the concrete elements.
Pros
- Keeps algorithm implementations separate from the classes of the objects they operate on.
- Makes it easy to add new operations without modifying the classes of the elements.
- Each visitor class encapsulates related operations, adhering to the Single Responsibility Principle.
Cons
- Requires changing all visitor classes when a new Element class is added, which can be intrusive.
- Visitors often need access to the private internals of Elements, which can break encapsulation.
Relation to other patterns
- Visitor can be used to apply operations over Composite structures, making it easy to perform operations on complex tree structures.
- Visitor and Iterator can be used together to traverse a complex data structure and perform operations on its elements.
- Visitor is like a powerful version of Command pattern, where the visitor can perform multiple operations on the element.

 go
 
 
 
package main

import (
 "fmt"
 "math"
)

// Shape is the interface that all shapes must implement, which is done
// implicitly here.
type Shape interface {
 Accept(visitor Visitor)
}

// Circle is a shape that has a radius.
type Circle struct {
 Radius float64
}

// Accept allows a visitor to visit the circle.
func (c *Circle) Accept(visitor Visitor) {
 visitor.VisitCircle(c)
}

// Rectangle is a shape that has a width and height.
type Rectangle struct {
 Width, Height float64
}

// Accept allows a visitor to visit the rectangle.
func (r *Rectangle) Accept(visitor Visitor) {
 visitor.VisitRectangle(r)
}

// Visitor is the interface that all visitors must implement
type Visitor interface {
 VisitCircle(*Circle)
 VisitRectangle(*Rectangle)
}

// DrawVisitor is a visitor that can draw shapes.
type DrawVisitor struct{}

// VisitCircle draws a circle.
func (d *DrawVisitor) VisitCircle(c *Circle) {
 fmt.Printf("Drawing a circle with radius: %.2f\n", c.Radius)
}

// VisitRectangle draws a rectangle.
func (d *DrawVisitor) VisitRectangle(r *Rectangle) {
 fmt.Printf("Drawing a rectangle with width: %.2f and height: %.2f\n", r.Width, r.Height)
}

// AreaVisitor is a visitor that can calculate the area of shapes.
type AreaVisitor struct {
 Area float64
}

// VisitCircle calculates the area of a circle.
func (a *AreaVisitor) VisitCircle(c *Circle) {
 a.Area = math.Pi * c.Radius * c.Radius
}

// VisitRectangle calculates the area of a rectangle.
func (a *AreaVisitor) VisitRectangle(r *Rectangle) {
 a.Area = r.Width * r.Height
}

func main() {
 circle := &Circle{Radius: 5}
 rectangle := &Rectangle{Width: 3, Height: 4}

 drawVisitor := &DrawVisitor{}
 circle.Accept(drawVisitor)
 rectangle.Accept(drawVisitor)

 areaVisitor := &AreaVisitor{}
 circle.Accept(areaVisitor)
 fmt.Printf("Circle Area: %.2f\n", areaVisitor.Area)

 rectangle.Accept(areaVisitor)
 fmt.Printf("Rectangle Area: %.2f\n", areaVisitor.Area)

 // Output:
 /*
 Drawing a circle with radius: 5.00
 Drawing a rectangle with width: 3.00 and height: 4.00
 Circle Area: 78.54
 Rectangle Area: 12.00
 */
}

Conclusion

Embarking on the journey through Object-Oriented Programming principles, Software Design Principles, and an array of design patterns, we’ve traversed the most common landscape of structured software design. From the encapsulation and abstraction of OOP to the SOLID foundations of software design, and through the diverse territories of Creational, Structural, and Behavioral patterns, this book summary serves as a compass for developers navigating the complexities of software architecture. Whether you’re refining your craft or laying the cornerstone of your development career, the insights and patterns presented by Alexander offer a blueprint for building software that stands the test of time, adaptable to the ever-evolving demands of technology and user needs. That was a very enjoyable read: recommended!

Resources and references

Book summary: Learning Go – An Idiomatic Approach to Real-World Go Programming

Sébastien Lavoie — Fri, 20 Oct 2023 20:08:00 -0600

Introduction

Go is a modern programming language developed by Google that has gained immense popularity in recent years. It is a statically typed, compiled language that combines aspects of imperative and object-oriented programming. Go aims to provide simplicity, performance, and reliability.

In his book, Jon provides a comprehensive introduction to Go programming. The book focuses on teaching idiomatic Go code by using concrete examples and focusing on how experienced Go developers structure their code. It covers fundamental language features like primitive types, control structures, and composite types. It also dives into more advanced topics like concurrency through goroutines and channels, writing tests, and using reflection.

This summary highlights the key takeaways from each chapter. It aims to provide an overview of the core concepts and best practices for writing clear, readable, robust Go code. It’s written from the perspective of a developer who has experience with other programming languages like Python, Java, and TypeScript but practically none in Go.

Setting Up Your Go Environment

Use golint to enforce the right coding style of a project.
Use go version to check the version of Go installed.
Use go vet to find errors that may not be detected by the compiler, such as having the wrong number of arguments passed to a Printf call.
A common idiom to run multiple commands at once when building a project is to rely on a Makefile like this:

 makefile
 
 
 
.DEFAULT_GOAL := build

fmt:
 go fmt ./...
.PHONY:fmt

lint: fmt
 golint ./...
.PHONY:lint

vet: fmt
 go vet ./...
.PHONY:vet

build: vet
 go build hello.go
.PHONY:build

Typing make will run fmt, then vet, then build since the default task is build, which requires vet to have run first, which in turn requires fmt to have run first, which in turn has no dependency, so fmt runs and the chain continues.

Testing whether a new version of Go works for existing programs compiled on an older version is straightforward:

 bash
 
 
 
go get golang.org/dl/go.1.x.y # replace x.y
go1.x.y download

# try out the changes
go1.x.y build

# If all good, remove this secondary version
go1.x.y env GOROOT
/.../.../go1.x.y
rm -rf $(go1.x.y env GOROOT)
rm $(go env GOPATH)/bin/go1.x.y

# Install new version as wanted...

Predeclared Types and Declarations

Predeclared types

Zero value
- Assigned to a variable that is declared with no initial value (doesn’t lead to bugs like in C or C++).
Literals
- These express different bases, such as 0b (binary), 0o (octal) or 0x (hexadecimal). As in other languages like Python or Java, underscores can be used to express large numbers by separating digits (e.g., 1_000_000).
- Floating point literals look like 6.03e23.
- Rune literals are represented with single quotes (no double quotes accepted). The most common ones are ('\n'), tab ('\t'), single quote ('\''), double quote ('\"') and backslash ('\\'). Other bases are supported but should be limited to specific contexts (e.g., bit filters for base two).
- String literals can be written with double quotes, where everything must be escaped.
- Raw string literals use backticks instead of double quotes and can be used to insert any character except a backtick. They support multiline expressions.
Boolean
- The type is bool and the default zero value is false.
Numeric types
- Integers
  - int8 (aliased byte, which is much more common), int16, int32, int64, uint8, uint16, uint32, uint64.
  - The zero value is 0.
  - Use the minimum size when needed for specific applications.
  - Use int64 and uint64 for library functions (suggested back when generics weren’t available).
  - Otherwise, just use int. Other types should be considered a premature optimization until proven otherwise.
  - Variables can be modified like so: +=, -=, *=, /= and %=.
  - Available comparisons are: ==, !=, >, >=, <, and <=.
  - Bit manipulations
    - Shifts: << (left), >> (right)
    - Logical bit masks: & (AND), | (OR), ^ (XOR), &^ (AND NOT)
    - These operators can be used to modify a variable as well: &=, |=, ^=, &^=, <<=, >>=.
Floating point types
- float32, float64.
- The zero value is 0.
- If using a floating point number, opt for float64 unless a profiler shows significant improvement with float32 and the precision is good enough (6-7 decimal places).
- Strict equality (or inequality) should not be done on floating point numbers: check the variance instead (less than epsilon).
Complex types
- complex64 uses float32 to represent real and imaginary parts, while complex128 uses float64, using the complex built-in function and real and image functions to extract the relevant parts.
- As with floating point numbers, use the epsilon technique to check for equality.
Strings and runes
- The zero value is an empty string.
- Strings are immutable.
- Strings can be checked for equality or compared for ordering (>, >=, <, or <=) and can be concatenated with the + operator.
- The rune type represents a single code point, equivalent to int32.
Explicit type conversion
- All type conversions are explicit.
- There is no concept of “truthiness” (e.g., if 2: print("ok") is valid in Python).

`var` vs. `:=`

var is more verbose but flexible:

 go
 
 
 
var x int = 1
var x = 1 // because the default type is `int`
var x int // no value => it will be the zero value
var x, y int = 1, 2 // multiple assignments
var x, y int // multiple assignments, zero values
var x, y = 1, "hi" // different default types

// Declaration list
var (
 x int
 y = 2
 z string
)

Type inference can be performed within a function:

 go
 
// These statements are equivalent
var x = 1
x := 1 // invalid syntax outside a function

Avoid := in the following situations:

When explicitly initializing a zero value, like var x int.
To avoid a type conversion, by writing var x byte = 8 instead of x := byte(8).
To avoid “shadowing” a variable, as := can be used to assign to existing variables. Create new variables with var.
Non-constant package-level variables are a bad idea. If they’re unused, they go unnoticed without raising compile-time errors.

`const`

Variables cannot be declared as immutable.
Constants are a way of giving names to literals.
Inside a function, it is clear when a variable is being modified.
If a constant is typed (e.g., const typedVar int = 1), then it can only be assigned to that type, int in this case.
If a constant is untyped (e.g., const untypedVar = 2), then it can be assigned to suitable numerical types.

Unused variables

Unused declared local variables result in a compile-time error.

Naming Variables and Constants

Even though many Unicode characters can be used, they should be avoided to maintain clarity.
Go uses camelCase.
The less scope a variable has, the shorter its name should be (k and v are accepted for key/value, just like i and j to use indices when iterating in loops).
It is common to use the first letter of a type as the variable name (e.g., i for integers, f for floats, b for boolean). If the code is hard to understand, it’s a sign the function is trying to do too much.

Composite Types

Arrays

They are rarely used directly.
They can be compared (== and !=).
Their length is retrieved with the built-in len function.
Negative indexing is a compile-time error.
Out-of-bounds indexing results in a panic at runtime.
Unless there’s a very specific need to use a given size of array (e.g., for a cryptographic library), avoid them.
They exist basically to provide slices.
- There are a few ways of declaring arrays:

 go
 
 
 
// indicate the size and type
var x [3]int // 3 integers assigned to the zero value

// array literal
var x = [3]int{10, 20, 30} // values specified
var x = [...]int{10, 20, 30} // equivalent

// sparse array:
// indicate few values at specific locations
var x = [12]int{1, 5: 4, 6, 10: 100, 15}

// Get and set values
x[0] = 10
fmt.Println(x[2])

Slices

The zero value for a slice is nil, which represents the lack of a value for some type. nil itself has no type.
The size of the array is not specified, making it a slice: var x = []int{10, 20, 30}. This is a slice literal.
Can be used like a sparse array: var x = []int{1, 5: 4, 6, 10: 100, 15}.
Multidimensional arrays can be simulated: var x [][]int.
Reads and assignments are the same as with arrays, using square brackets.
Slices can be created without assigning initial values: var x []int.
Slices aren’t comparable, except to check if it is nil (x == nil).
They’re useful for sequential data.

`len`

A nil slice returns 0 (len(x)).

`append`

It it used to grow slices:

 go
 
 
 
var x []int
x = append(x, 10) // returns a slice
x = append(x, 5, 6, 7) // more than one value

// append to another slice with `...`
// Similar to the spread operator in JavaScript,
// but it goes after the value to spread
y := []int{20, 30, 40}
x = append(x, y...)

Capacity

It increases automatically as needed. It doubles under 1,024 items, then it increases by at least 25%.
cap returns the current capacity of the slice.
It is better when possible to allocate the needed size upfront to avoid resizing the arrays.

`make`

It can be used to create a slice that already has a capacity specified.
- x := make([]int, 5): length and capacity of 5 (all zero values). Using append here would add new values to the end of the slice, after the zero values!
- x := make([]int, 0, 10) creates an empty slice with a capacity of 10 and after x = append(x, 5,6,7,8), it contains [5 6 7 8].

Emptying a slice

Available since Go 1.21 with the built-in clear function.
This sets all elements of the slice to their zero value.

 go
 
 
 
x := []int{1, 2, 3, 4}
fmt.Println(x) // [1 2 3 4]
clear(x)
fmt.Println(x) // [0 0 0 0]

y := []string{"a", "b", "c"}
fmt.Println(y) // [a b c]
clear(y)
fmt.Println(y) // [ ] (empty strings)

Declaring a slice

Slice literals
- An empty slice literal declares a slice that is non-nil: var x = []int{}. This is useful to convert to JSON.
- Useful with some initial values or when the values don’t change.

Slicing slices

These work with square brackets:

 go
 
 
 
x := []int{1, 2, 3, 4} // [1 2 3 4]
y := x[:2] // [1 2]
z := x[1:] // [2 3 4]
d := x[1:3] // [2 3]
e := x[:] // [1 2 3 4]

 go
 
 
 
x := []int{1, 2, 3, 4}
y := x[:2]
z := x[1:]

// These are bidirectional changes!
x[1] = 20 // affects `x`, `y` and `z`
y[0] = 10 // affects `x` and `y`
z[1] = 30 // affects `x` and `z`

// Result:
// x: [10 20 30 4]
// y: [10 20]
// z: [20 30 4]

append can lead to unintuitive results, overwriting existing values:

 go
 
 
 
x := make([]int, 0, 5) // length 0, capacity 5
x = append(x, 1, 2, 3, 4) // x is now [1 2 3 4]
y := x[:2] // [1 2], length 2, capacity 5
z := x[2:] // [3 4], length 2, capacity 3

y = append(y, 30, 40, 50)
// x is now [1 2 30 40], length 4, capacity 5!
// y is now [1 2 30 40 50], length 5, capacity 5
// z is now [30 40], length 2, capacity 3

x = append(x, 60)
// x is now [1 2 30 40 60], length 5, capacity 5
// y is now [1 2 30 40 60], length 5, capacity 5!
// z is still [30 40], length 2, capacity 3

z = append(z, 70)
// x is now [1 2 30 40 70], length 5, capacity 5!
// y is now [1 2 30 40 70], length 5, capacity 5!
// z is now [30 40 70], length 3, capacity 3

One way to avoid this issue is to use full slice expressions to indicate the capacity of the sub-slices:

 go
 
 
 
x := make([]int, 0, 5)
x = append(x, 1, 2, 3, 4)
y := x[:2:2] // take a slice of x, up to index 2, with a capacity of 2
z := x[2:4:4] // take a slice of x, from index 2 to 4, with a capacity of 2

y = append(y, 30, 40, 50)
// x is still [1 2 3 4], length 4, capacity 5
// y is now [1 2 30 40 50], length 5, capacity 6
// z is still [3 4], length 2, capacity 2

x = append(x, 60)
// x is now [1 2 3 4 60], length 5, capacity 5
// y is still [1 2 30 40 50], length 5, capacity 6
// z is still [3 4], length 2, capacity 2

z = append(z, 70)
// x is still [1 2 3 4 60], length 5, capacity 5
// y is still [1 2 30 40 50], length 5, capacity 6
// z is now [3 4 70], length 3, capacity 4

Converting Arrays to Slices

Arrays can be sliced, though memory will be shared as when slicing a slice.

 go
 
 
 
x := [4]int{5, 6, 7, 8} // [5 6 7 8]
y := x[:2] // [5 6]
z := x[2:] // [7 8]
x[0] = 10 // [10 6 7 8]
// y and z are now [10 6] and [7 8]

Converting Slices to Arrays

Data in the slice is copied to new memory (slices and arrays remain independent).
A slice converted into a pointer to an array will share the same underlying data and memory address.

 go
 
 
 
x := []int{1, 2, 3, 4} // [1 2 3 4]
y := x // y is a slice, not a copy
z := make([]int, 4) // [0 0 0 0]
copy(z, x) // copy(dst, src)
x[0] = 10 // [10 2 3 4]
// y is now [10 2 3 4]
// z is now [1 2 3 4]

`copy`

It creates a slice that is independent from the original slice.

 go
 
 
 
// It can copy the whole slice if the lengths are the same
x := []int{1, 2, 3, 4} // [1 2 3 4]
y := make([]int, 4) // [0 0 0 0]
num := copy(y, x) // num=4, copy(dst, src)
fmt.Println(y, num) // [1 2 3 4] 4
fmt.Println(x) // [1 2 3 4]

// It can copy a subset of the slice
y := make([]int, 2) // [0 0]
num = copy(y, x) // num=2, copy(dst, src)
fmt.Println(y) // [1 2]

// It can copy from a subset from any position
x := []int{1, 2, 3, 4} // [1 2 3 4]
y := make([]int, 2) // [0 0]
copy(y, x[2:]) // copy(dst, src)
fmt.Println(y) // [3 4]

num = copy(x[:3], x[1:]) // put the last 3 values at the beginning
fmt.Println(x) // [2 3 4 4], overwriting

// It also works with arrays
x := []int{1, 2, 3, 4} // slice, [1 2 3 4]
d := [4]int{5, 6, 7, 8} // array, [5 6 7 8]
y := make([]int, 2) // [0 0]
copy(y, d[:]) // first 2 values of d into y
fmt.Println(y) // [5 6]
copy(d[:], x) // copy x into d
fmt.Println(d) // [1 2 3 4]

Strings and Runes and Bytes

Strings are arrays of bytes.
Single characters can be extracted from a string with an index expression:

 go
 
 
 
s := "hello"
c := s[0] // c is a byte, not a rune
fmt.Println(c) // 104
fmt.Printf("%T\n", c) // uint8 (i.e., byte)

// Need to be careful with indexing
var s string = "Hello 😄"
fmt.Println(len(s)) // could have expected 7, but it's 10
fmt.Println(s[:2], s[7:]) // He ���: the emoji is 4 bytes long

Maps

The built-in map type is a hash map (implemented as an array).
The zero value for a map is nil.
Writing to a nil map results in a runtime panic.
len on a map returns the number of key/value pairs.
Maps are not comparable (but they can check against nil).
The key must be comparable: it cannot be a slice, map or function.
Maps are good when the order of the keys doesn’t matter: use a slice when it does.
All the values must be of the same type, but the keys can be of different types.
Avoid using them as input parameters to functions (use a struct instead to be self-documenting).

 go
 
 
 
var nilMap map[string]int
// ^ ^
// key type value type

// map literal: length of 0
myMap := map[string]int{} // allows reads and writes

// Non-empty map
reposByOrg := map[string][]string{
 "dbeaver": []string{"dbeaver", "cloudbeaver", "team-edition-deploy"},
 "slidevjs": []string{"slidev", "slidev-vscode", "themes"},
 "ReactiveX": []string{"RxJava", "rxjs", "RxGo"}, // comma at the end here too
}

// With a default size
myValues := make(map[int][]string, 10) // length 0, capacity 10, can grow beyond 10

Reading and writing maps

 go
 
 
 
reposByOrgStars := map[string]int{} // length 0, can grow, string to integer
reposByOrgStars["dbeaver"] = 10 // write
reposByOrgStars["slidevjs"] = 100 // write
reposByOrgStars["ReactiveX"]++ // read, increment, write (0 -> 1)
// reposByOrgStars["slidevjs"] := 100 // invalid syntax

Comma Ok idiom

One can get the value of a key and a boolean indicating whether the key exists or not:

 go
 
value, ok := reposByOrgStars["dbeaver"] // 10 true
value, ok = reposByOrgStars["notfound"] // 0 false

Deleting from a map

delete removes a key/value pair from a map:

 go
 
 
 
delete(reposByOrgStars, "ReactiveX")

// It is safe to delete a key that doesn't exist
delete(reposByOrgStars, "notfound") // it returns nothing

// It is safe to delete a key from a nil map
var nilMap map[string]int
delete(nilMap, "notfound")

// It is safe to delete a key from an empty map
emptyMap := map[string]int{}
delete(emptyMap, "notfound")

Using maps as sets

Go doesn’t have a built-in set type.
A map can be used as a set by using the key as the value and the value as a boolean:

 go
 
 
 
mySet := map[string]bool{}
mySet["hello"] = true
mySet["world"] = true
mySet["hello"] = true // no error, but it's still a set

This works because if the value isn’t found, the zero value is returned, which is false for booleans.
To use operations like union, intersection and difference, the most convenient solution is to use a third-party library.
Structs can also be used as sets as they’re more memory efficient, but more clumsy to use as they make use of the comma ok idiom.

Structs

Good when there is related data that needs to be grouped together.
They are defined with the type keyword.
No commas are needed between fields.
They can be defined inside or outside of a function. If inside a function, they can only be used inside that function.

 go
 
 
 
type user struct {
 age int
 firstName string
 lastName string
}

var u user // zero value for a struct is all zero values for its fields
u.age = 18
u.firstName = "Bob"
u.lastName = "Michigan"
fmt.Println(u) // {18 Bob Michigan}

// Assignments can also be done with a struct literal
bob := user{} // also initializes all fields to zero values

// With initial values
jeremy := user{
 49, // must match the order of the fields
 "Jeremy", // all fields must be specified
 "Stretchy",
} // {49 Jeremy Stretchy}

// With this style, fields can be left out:
otherUser := user{
 age: 32, // using the field name...
 firstName: "Sweaty", // cannot indicate other fields without the field name
 // lastName is zero value, i.e., empty string
}

// Accessing a field:
jeremy.firstName = "Jer"
fmt.Println(jeremy.firstName) // Jer

Anonymous structs

They are useful when a struct is only used in one place.
Useful when marshalling and unmarshalling data.

 go
 
 
 
computer := struct {
 operatingSystem string
 chip string
}{
 operatingSystem: "macOS",
 chip: "Apple M2 Ultra",
}

Comparing and converting structs

Contrary to regular structs, they can be compared.

Blocks, Shadows, and Control Structures

Blocks

A block is a place where declarations are made.
The top-level block is the package block.
The import statements are in the file block.

Shadowing Variables

There is a “global” block, the universe block, which contains the built-in functions and types. Careful: those keywords can be shadowed!

 go
 
 
 
func main() {
 x := 10
 if x > 5 {
 fmt.Println(x)
 x := 5 // shadowing
 fmt.Println(x)
 }
 // x is still 10 here (outer block)
 fmt.Println(x)
}

func main() {
 x := 10
 if x > 5 {
 // x is shadowed while y is declared!
 x, y := 5, 20
 fmt.Println(x, y) // 5 20
 }
 fmt.Println(x) // 10
}

func main() {
 x := 10
 fmt.Println(x)
 fmt := "shadowing fmt package"
 fmt.Println(fmt) // undefined!
}

Linters typically won’t catch shadowing, but we can install shadow:

bash

go install golang.org/x/tools/go/analysis/passes/shadow/cmd/shadow@latest

And we can make it part of the Makefile:

 makefile
 
 
 
lint: fmt
 golint ./...
 shadow ./...
.PHONY: lint

`if` statements

The condition must be a boolean expression.
The usual flow is if ... {...} else if ... { ... } else { ... }.
There are no parentheses around the condition.
Variables can be scoped to the if statement (they’ll be available in else if and else blocks as well). Only use that feature to define new variables!

 go
 
 
 
if n := rand.Intn(10); n == 0 {
 fmt.Println("That's too low")
} else if n > 5 {
 fmt.Println("That's too big:", n)
} else {
 fmt.Println("That's a good number:", n)
}
// n is not available here!

`for` loops

It is the only looping construct in the language.
It can be used in four different ways to accomplish all looping needs.
It uses no parentheses.

Complete `for` statement

 go
 
for i := 0; i < 10; i++ {
 fmt.Println(i)
}

The initialization statement is executed once before the loop starts. It must use the := operator. It can shadow variables.
The second statement is the condition. It must be a boolean expression. It is checked before each iteration as well as before the loops starts.
The third statement is the post statement. It is executed after each iteration. It would usually be used to increment a counter.

Condition-only `for` Statement

 go
 
 
 
i := 0
for i < 10 {
 fmt.Println(i)
 i++
}

This is a statement that only has a condition. It is equivalent to a while loop in other languages.

Infinite `for` Statement

 go
 
for {
 fmt.Println("Hello")
}

This is a statement that has no condition. It is equivalent to a while true loop in other languages.

`break` and `continue`

There is no do... while construct as in other languages like C, Java or JavaScript.
do... while indicates how to stay in the loop while for indicates how to leave the loop.
break exits the loop.
continue skips the rest of the loop and goes to the next iteration. Use it to avoid nesting loops.
break and continue can be used with labels to break out of nested loops.

`for-range` loop

 go
 
 
 
odds := []int{1, 3, 5, 7, 9}
for i, v := range odds {
 fmt.Println(i, v)
}

Here, i (0 to 4) is the index of the iterator construct and v (1, 3 ... 9) is the value.
i is usually used for arrays, slices and strings, while k is used for maps.
As in other languages like Python, use an underscore (_) to ignore a value. The index or key can be ignored this way.
If the key is needed but not the value, leave the value out: for k := range myMap { ... }. This is useful when using a map as a set.

Iterating over maps

 go
 
 
 
m := map[string]int{"a": 1, "c": 3, "b": 2}
for i := 0; i < 3; i++ {
 fmt.Println("Loop", i)
 for k, v := range m {
 fmt.Println(k, v) // order will differ
 }
}
fmt.Println(m) // will be in ascending order to help with debugging

For security reasons (hash DoS), the order of the keys is randomized. If the order is important, use a slice of keys instead.

Iterating over strings

Go iterates over the Unicode code points (runes), not the bytes.

 go
 
 
 
samples := []string{"hello", "worl∂!"}
for _, sample := range samples {
 for i, r := range sample {
 fmt.Println(i, r, string(r))
 }
 fmt.Println()
}

/*
Output:
0 104 h // index, rune, string(rune)
1 101 e
2 108 l
3 108 l
4 111 o
 // first string is 5 runes long
0 119 w
1 111 o
2 114 r
3 108 l
4 8706 ∂ // this is a single rune: it occupies 3 bytes
7 33 ! // index 7! The second string is 8 runes long
*/

`for-range` value is a copy

Modifying the value variable doesn’t change the original value.
break and continue are also available in this form.

 go
 
 
 
odds := []int{1, 3, 5, 7, 9}
for _, v := range odds {
 v += 2
}
fmt.Println(odds) // [1 3 5 7 9]

`for` loop labels

While their use is rare, they can be used to break out of nested loops.
The label is indented to the same level as the containing block.

 go
 
 
 
 samples := []string{"hello", "worl∂!"}
outer:
 for _, sample := range samples {
 for i, r := range sample {
 fmt.Println(i, r, string(r))
 if r == 'l' {
 continue outer
 }
 }
 fmt.Println()
 }

/* Output:
0 104 h
1 101 e
2 108 l
0 119 w
1 111 o
2 114 r
3 108 l
*/

This code will skip the remaining letters of both words once the first l is printed out for each one.

The right `for` statement

for-range is the proper way to iterate over strings to get runes.
A complete for statement is good when not iterating through all the items in a collection (except for strings since runes aren’t necessarily one byte long).
The condition-only for statement is used to replace while loops.
Infinite loops can simulate a do... while construct and can be used to create the iterator pattern.

Expression `switch` statements

They don’t use parentheses.
Used to check for equality.
Scoped variables can be declared (e.g., word is scoped to all cases).
All cases are part of the same block (only the switch statement itself is a block surrounded by braces).
No need for break statements. It can be used, but may indicate a code smell.
break can be useful if the switch statement is inside a loop.
There is a fallthrough keyword to go to the next case (not recommended).

 go
 
 
 
words := []string{"Go", "Ada", "COBOL", "C++", "Python", "Clojure", "WebAssembly"}
for _, word := range words {
 switch size := len(word); size {
 case 1, 2, 3, 4: // catches multiple matches
 fmt.Println(word, "is a short name!") // Go, Ada, C++
 case 5:
 wordLen := len(word)
 fmt.Println(word, "is the right length:", wordLen) // COBOL
 case 6, 7, 8, 9: // empty case, nothing happens: Python, Clojure
 default:
 fmt.Println(word, "is a long name!") // WebAssembly
 }
}

// Inside a loop
loop: // label
for i := 0; i < 10; i++ {
 switch {
 case i%2 == 0:
 fmt.Println(i, "is even")
 case i%3 == 0:
 fmt.Println(i, "is divisible by 3 but not 2")
 case i%7 == 0:
 fmt.Println("exit the loop!")
 break loop // break out of the loop, not just the switch statement
 default:
 fmt.Println(i, "is boring")
 }
}

Blank `switch` statements

Instead of checking for equality, they check for any boolean comparison.

 go
 
 
 
func main() {
 var x int = 5
 switch {
 case x%2 == 0:
 fmt.Println(x, "is even")
 case x > 6:
 fmt.Println(x, "is large")
 case x <= 6:
 fmt.Println("Got it!") // this is the one that will be executed
 default:
 fmt.Println(x, "Not it...")
 }
}

`if` or `switch`?

switch should be used when there is some relationship between comparable elements. It is more concise and makes the comparisons more obvious.

`goto`

It should generally be avoided.
It can be used to replace boolean flags, such as in this non-trivial example from the standard library.

Functions

Declaring and calling them

Go has no classes, but it has methods (see chapter 7).
Types are mandatory.
The return keyword is mandatory (except for main) if the function has a return type.
Nothing goes between the input parameters and the start of the block if there’s no return type.
Go has no named or optional input parameters: you can pass structs instead. In practice, that probably means the function is trying to do too much if you need this feature.
Go supports variadic parameters (e.g., the fmt.Println function) with ... right before the type: they are used as a slice inside the function.
Functions can return multiple values. They must all be returned, comma-separated. Unlike Python which uses tuples, Go uses the comma to separate the individual values.
The error is always the last parameter a function will return. If no error occurred, it will be nil.
Indicate ignored values (possibly all) with an underscore. A notable exception is fmt.Println which returns two values that aren’t usually used.
Named values can be returned. They make shadowing possible and should be used sparingly.
Blank returns can be returned with named values, but they make it harder to understand how data flows.

 go
 
 
 

func div(numerator int, denominator int) int {
// ^ ^ ^ ^
// | input parameter | return type
// Function name parameter type
 if denominator == 0 {
 return 0
 }
 return numerator / denominator
}

// The following is equivalent when the types are the same
// func div(numerator, denominator int) int ...

// variadic parameter
func addTo(base int, vals ...int) []int {
 out := make([]int, 0, len(vals))
 for _, v := range vals {
 out = append(out, base+v)
 }
 return out
}
// fmt.Println(addTo(1, 2, 3, 4))
// a := []int{4, 3}
// fmt.Println(addTo(3, a...))
// fmt.Println(addTo(3, []int{4, 5}...))

// named return values
func divAndRemainder(numerator int, denominator int) (result int, remainder int, err error) { ... }

Functions are values

Functions can be defined as types, e.g., type aFuncType func(int, int) int.
Anonymous functions can be defined inside other functions and called immediately (IIFE). This comes in handy when using defer and Goroutines.

Closures

Closures are used to create functions that have access to variables that are outside of their scope.
Functions can be passed as parameters to other functions.
Functions can return functions.
They are useful with sort.Search and sort.Slice.

An example of closure is with the sort.Slice function:

 go
 
 
 
import (
 "fmt"
 "sort"
)

func main() {
 type Person struct {
 FirstName string
 LastName string
 Age int
 HasPet bool
 }
 people := []Person{
 {"Pat", "Patterson", 37, true},
 {"Tracy", "Bobbert", 23, false},
 {"Fred", "Fredson", 18, true},
 {"Bob", "Tracier", 18, false},
 {"Alice", "Anderson", 30, true},
 }
 fmt.Println(people)

 // `people` is captured by the closure
 sort.Slice(people, func(i int, j int) bool {
 // If one person has a pet and the other doesn't,
 // prioritize the one with the pet.
 if people[i].HasPet != people[j].HasPet {
 return people[i].HasPet
 }
 // If both have pets, sort by LastName.
 if people[i].HasPet && people[j].HasPet {
 return people[i].LastName < people[j].LastName
 }
 // Otherwise, sort by age in ascending order.
 return people[i].Age < people[j].Age
 })

 fmt.Println(people)
}

// This returns:
// - People that have pets first
// - If both have pets, sort by last name in ascending order
// - If neither have pets, sort by age in ascending order

// Unsorted:
[
 {Pat Patterson 37 true}
 {Tracy Bobbert 23 false}
 {Fred Fredson 18 true}
 {Bob Tracier 18 false}
 {Alice Anderson 30 true}
]

// Sorted:
[
 {Alice Anderson 30 true}
 {Fred Fredson 18 true}
 {Pat Patterson 37 true}
 {Bob Tracier 18 false}
 {Tracy Bobbert 23 false}
]

A function that returns a function:

 go
 
 
 
func main() {
 withTwo := getResult(2)
 withThree := getResult(3)
 for i := 0; i < 3; i++ {
 fmt.Println("i=", i, "withTwo (2 + i):", withTwo(i), "withThree (3 + i):", withThree(i))
 }
}

func getResult(initialValue int) func(int) int {
 return func(subsequent int) int {
 return initialValue + subsequent
 }
}

// Output:
// i= 0 withTwo (2 + i): 2 withThree (3 + i): 3
// i= 1 withTwo (2 + i): 3 withThree (3 + i): 4
// i= 2 withTwo (2 + i): 4 withThree (3 + i): 5

`defer`

This is used to perform the cleanup code, such as closing a file, after a function has returned. This is similar to the finally block in Java or Python but it executes at the very end of the function, not as part of a try...except block.
It delays the execution of a function until the surrounding function returns.
They run in LIFO (last in, first out) order.
The code that runs after defer is literally the last thing that runs before the function returns, so what is put there is immediately “called” (e.g., defer close()) but will run until later.
It helps reduce depth of nesting, which, along with “lack of structure”, are two of the most important factors that contribute to code complexity (see this paper).

Go is “call by value”

Go always makes a copy of the value before passing it to a function.
Maps and slices behave differently because they are implemented with pointers.

Pointers

A pointer is a variable that holds the address of a value in memory.
The zero value of a pointer is nil.
& is the address-of operator. It goes before the variable name to get its address.
* is the indirection operator (dereference). It goes before a pointer to get the value it points to.
Dereferencing a nil pointer will result in a runtime panic.
Types with an * are pointers to that type (“pointer type”).
new is a built-in function that allocates memory for a type and returns a pointer to it.
To turn a constant into a pointer, use a helper function that takes a value and returns a pointer to it.
A pointer is used to indicate that a parameter is mutable, i.e., that the function can modify the original value.
To update the value of a pointer inside a function, dereference it and assign it a new value.
Value types should be preferred when returning from functions.
Use a pointer as a return type when there is a need to return a modified data structure or when the data being passed around is very large (at least 1 MB).
Slices can be used as buffers when iterating over files to avoid allocating memory in each iteration of the loop.
The garbage collector will free memory that is no longer used. Go favors low latency over high throughput.

 go
 
 
 
var x int = 10
var y *int = &x
fmt.Println(x, y) // 10 0xc0000b4008
fmt.Println(&x, *y) // 0xc0000b4008 10

// The zero value of a pointer is nil
var z *int
fmt.Println(z) // nil

// Dereferencing a nil pointer will result in a runtime panic
// fmt.Println(*z) // panic: runtime error: invalid memory address or nil pointer dereference

// new allocates memory for a type and returns a pointer to it
var a *int = new(int)
fmt.Println(a) // 0xc0000b4010
fmt.Println(*a) // 0

// To turn a constant into a pointer, use a helper function that takes a value
// and returns a pointer to it
func intPtr(i int) *int {
 return &i
}
var b *int = intPtr(10)

// A pointer is used to indicate that a parameter is mutable
func addOne(x *int) {
 *x++
}
addOne(b)
fmt.Println(*b) // 11

// To update the value of a pointer inside a function, dereference it and assign it a new value
func updatePointer(x *int) {
 *x = 2
}
updatePointer(b)
fmt.Println(*b) // 2

Types, Methods, and Interfaces

Types can be declared at any level, including at the package level.

Methods

Method names cannot be overloaded.

 go
 
 
 
type Person struct {
 FirstName string
 LastName string
 Age int
}

func (p Person) String() string {
// ^
// p is a receiver of the String method
 return fmt.Sprintf("%s %s, age %d", p.FirstName, p.LastName, p.Age)
}

func main() {
 p := Person{"Domi", "Noes", 42}
 fmt.Println(p.String()) // Domi Noes, age 42
}

Pointer Receivers and Value Receivers

Use a pointer receiver when the method needs to modify the receiver.
Use a pointer receiver when nil must be handled.
A value receiver is used when the method doesn’t need to modify the receiver.
If a type has a pointer receiver, all methods should have pointer receivers for consistency.
Usually, there’s no need for getters and setters when using structs: just use the fields directly.
Pointer receiver methods should check for nil values.

Methods are also functions

We can use a method value to turn a method into a function.
A method expression is used to turn a method into a function that takes the receiver as the first parameter.
They can be use for dependency injection.

 go
 
 
 
// Using a method value
func main() {
 p := Person{"Domi", "Noes", 42}
 f := p.String // using an instance of the struct
 fmt.Println(f()) // Domi Noes, age 42
}

// Using a method expression
func main() {
 p := Person{"Domi", "Noes", 42}
 f := Person.String // using the type itself
 fmt.Println(f(p)) // Domi Noes, age 42
}

Functions vs. methods

Use a function when there is no need to modify the receiver.
Use a method with a struct receiver when there is a need to modify data at runtime.

Type declarations are not inheritance

Declaring a type based on another type is not inheritance: there is no hierarchy.
Type conversion is used to convert a value from one type to another.

Types serve as executable documentation

They can be used to make code more readable and self-documenting.
A Percentage type can be used to make it clear what a value is instead of an int.

Use iota for enumeration (sparingly)

Go does not have an enumeration type.
iota is a built-in constant generator that starts at 0 and increments by 1 for each subsequent constant.
iota can be used to create a set of constants that are related to each other.
It should be used for “internal” purposes only, when the constants are referred to by name – not by value.
It is useful to differentiate between sets of values, not to rely explicitly on the values themselves.
If the first value in the constant block (with value 0) is not really initialized or the value 0 does not make sense, it can be named with an _ to skip 0.

 go
 
 
 
type Color int

const (
 Red Color = iota
 Green
 Blue
)

func main() {
 fmt.Println(Red, Green, Blue) // 0 1 2
}

Embedding for composition

Types can be embedded to encourage composition.

 go
 
 
 
type Person struct {
 FirstName string
 LastName string
 Age int
}

type Employee struct {
 Person // embedded field
 EmployeeID int
}

func main() {
 e := Employee{
 Person: Person{
 FirstName: "Domi",
 LastName: "Noes",
 Age: 42,
 },
 EmployeeID: 12345,
 }
 fmt.Println(e.FirstName, e.LastName, e.Age, e.EmployeeID) // Domi Noes 42 12345
}

Interfaces

Interfaces are declared as a type with the interface keyword.
The methods defined in an interface are the methods that a type must implement to be considered an implementation of that interface: this is referred to as the method set.
They can be declared in any block.
They usually end with er (e.g., Stringer, Reader, Writer).
They are implemented implicitly.
Go is a blend of duck typing (e.g., dynamic behavior in Python) and structural typing (Java interfaces).
Use built-in interfaces from the standard library as much as possible.
Just like structs, interfaces can be embedded.
Interfaces are the only abstract type in Go.

 go
 
 
 
// Switching between the logic providers is as simple as changing the type of the L field.
import "fmt"

type LogicProvider struct{}

type LogicProvider2 struct{}

func (lp LogicProvider2) Process(data string) string {
 fmt.Println("LogicProvider2: Process")
 return data
}

func (lp LogicProvider2) Rework(data string) string {
 return data
}

func (lp LogicProvider) Process(data string) string {
 return data
}

func (lp LogicProvider) Rework(data string) string {
 fmt.Println("LogicProvider1: Rework")
 return data
}

type Logic interface {
 Process(data string) string
 Rework(data string) string
}
type Client struct {
 L Logic
}

func (c Client) Program() {
 data := "data"
 c.L.Process(data)
 c.L.Rework(data)
}

func main() {
 c1 := Client{
 L: LogicProvider{},
 }
 c1.Program()

 c2 := Client{
 L: LogicProvider2{},
 }
 c2.Program()
}

// Output:
// LogicProvider1: Rework
// LogicProvider2: Process

Take interfaces and return structs

Returning interfaces increases coupling.
It is better to return structs and take interfaces as parameters.

Empty interfaces

If an interface is nil, invoking a method on it will result in a runtime panic.
An empty interface matches any type, because it requires implementing no methods.
They can be used when receiving data from an external source (e.g., a database or JSON) and the type is unknown.
Using interface{} is a code smell: it should be used sparingly.

Type assertions and type switches

Use the comma ok idiom to avoid a type assertion from panicking.
Type assertions are checked at runtime.
Type conversions are checked at compile time.
A type switch is used to check the type of an interface.
In the case of errors, use errors.Is and errors.As to test for specific errors.
Add a default case to switch statements to catch unexpected types.
It can be safer to keep interfaces unexported.

 go
 
 
 
func main() {
 var i interface{} = 42
 v1, ok1 := i.(int)
 fmt.Println(v1, ok1) // 42 true
 v2, ok2 := i.(string)
 fmt.Println(v2, ok2) // "" false

 // type switch
 switch v := i.(type) {
 case int:
 fmt.Println("int", v) // int 42
 case string:
 fmt.Println("string", v)
 case float64, float32: // check both at once
 fmt.Println("float", v)
 default:
 fmt.Println("unknown", v)
 }

 // type assertion using optional interface
 if s, ok := i.(MySpecificInterface); ok {
 // myInterface satisfies MySpecificInterface
 s.SpecificMethod()
 }
}

Function types are a bridge to interfaces

Functions can implement interfaces.
Go uses this to implement the http.Handler interface.
Small interfaces are encouraged.
If a function can depend on many other functions, it is better to use a struct with methods.

 go
 
 
 
type HandlerFunc func(http.ResponseWriter, *http.Request)

func (f HandlerFunc) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 f(w, r)
}

func main() {
 http.Handle("/", HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 fmt.Fprintln(w, "Hello, world!")
 }))
 http.ListenAndServe(":8080", nil)
}

An actual, basic HTTP server:

 go
 
 
 
package main

import (
 "fmt"
 "net/http"
)

type HandlerFunc func(http.ResponseWriter, *http.Request)

func (f HandlerFunc) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 f(w, r)
}

func main() {
 http.Handle("/", HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 p, err := fmt.Fprintln(w, "Hello, world!")
 if err != nil {
 return
 }
 fmt.Println(p)
 }))
 err := http.ListenAndServe(":8080", nil)
 if err != nil {
 return
 }
}

Implicit Interfaces Make Dependency Injection Easier

“[…] code should explicitly specify the functionality it needs to perform its task”.
If a type has methods that match an interface’s signature, it implicitly satisfies that interface.
Go’s implicit interfaces make dependency injection easier.
Interfaces are used to decouple code.
The client’s code should not be responsible for creating the dependencies it needs.
The client’s code defines the interfaces and can customize the method set it needs.

Here is an example of an implicit interface:

 go
 
 
 
package main

import "fmt"

type Talker interface {
 Say() string
}

// Dog implicitly implements the Talker interface
type Dog struct{}

func (d Dog) Say() string {
 return "Woof!"
}

func Speak(t Talker) {
 fmt.Println(t.Say())
}

func main() {
 d := Dog{}
 Speak(d) // Woof!
}

And an example demonstrating dependency injection:

 go
 
 
 
package main

import (
 "fmt"
)

// Logger is an implicit interface with a Log method
type Logger interface {
 Log(message string)
}

// SimpleLogger implicitly satisfies Logger by implementing Log
type SimpleLogger struct{}

func (sl SimpleLogger) Log(message string) {
 fmt.Println(message)
}

// AdvancedLogger implicitly satisfies Logger by implementing Log
type AdvancedLogger struct{}

func (al AdvancedLogger) Log(message string) {
 fmt.Println("ADVANCED: " + message)
}

// CompositeLogger combines SimpleLogger and AdvancedLogger
// Again, it implicitly satisfies Logger by implementing Log
type CompositeLogger struct {
 loggers []Logger
}

// Log messages with multiple loggers
func (cl CompositeLogger) Log(message string) {
 for _, logger := range cl.loggers {
 logger.Log("[CompositeLogger] " + message)
 }
}

// Greeter contains logic to greet
type Greeter struct {
 logger Logger // Logger is injected
}

// NewGreeter injects dependencies and returns a new Greeter
func NewGreeter(l Logger) Greeter {
 return Greeter{logger: l}
}

// Greet uses the Logger to log a greeting
func (g Greeter) Greet() {
 g.logger.Log("Hello, dependency injection and implicit interface!")
}

func main() {
 logger1 := SimpleLogger{} // Create Logger
 greeter1 := NewGreeter(logger1) // Inject Logger into Greeter
 greeter1.Greet() // Use Greeter
 // Logs:
 // Hello, dependency injection and implicit interface!

 logger2 := AdvancedLogger{} // Create Logger
 greeter2 := NewGreeter(logger2) // Inject Logger into Greeter
 greeter2.Greet() // Use Greeter
 // Logs:
 // ADVANCED: Hello, dependency injection and implicit interface!

 logger3 := CompositeLogger{loggers: []Logger{SimpleLogger{}, AdvancedLogger{}}}
 greeter3 := NewGreeter(logger3) // Inject CompositeLogger into Greeter
 greeter3.Greet() // Use Greeter
 // Logs:
 // [CompositeLogger] Hello, dependency injection and implicit interface!
 // ADVANCED: [CompositeLogger] Hello, dependency injection and implicit interface!
}

Generics

Generics Reduce Repetitive Code and Increase Type Safety

Generics are “type parameters” that allow one to write functions and data structures that can work with any type.
They reduce repetitive code and increase type safety.

Generic Functions Abstract Algorithms

Generic functions can be used to abstract algorithms.
They can be used to write functions that work with any type.

 go
 
 
 
package main

import "fmt"

// Max returns the maximum of two values
func Max[T any](a, b T) T {
 if a > b {
 return a
 }
 return b
}

Generics and interfaces

Generics can be used with interfaces.
They can be used to write functions that work with any type that satisfies an interface.

 go
 
 
 
package main

import "fmt"

// Stringer is an interface with a String method
type Stringer interface {
 String() string
}

// Print calls the String method on a value that satisfies the Stringer interface
func Print[T Stringer](s T) {
 fmt.Println(s.String())
}

Errors

Go does not have exceptions.
Errors are values.
They are the last return value of a function (by convention).
The error interface is defined in the standard library.
The errors package is used to create errors.
The fmt package is used to print errors.
The errors.Is function is used to check for specific errors.
The errors.As function is used to check for specific errors and get the underlying error.
The errors.Unwrap function is used to get the underlying error, but errors.Is and errors.As are more commonly used for this.
The errors.New function is used to create errors.
The errors.Errorf function is used to create errors with formatting.
When a function returns an error, it is expected that the caller will check for it.
If a function does not return an error, its value will be nil, because it is the zero value for interfaces.
Error messages should not be capitalized or end with punctuation, nor contain newline.
Because all values must be read, errors cannot be ignored implicitly.
Because the main code is unindented and the error handling code is indented, the code’s purpose is easier to follow.

Sentinel errors

Sentinel errors are errors that are predefined and can be checked for equality.
They are defined at the package level.
They start with Err (except for io.EOF).
They should be treated as read-only.
They are used to indicate it is not possible to continue processing (e.g., ErrFormat for ZIP files).
Whenever possible, use existing sentinel errors from the standard library.

Wrapping errors

To give additional context to an error, wrap it with fmt.Errorf.
A series of errors can be wrapped with fmt.Errorf and errors.Unwrap: these are called error chains.
If context is not required, a brand new error can be created with errors.New or errors.Errorf.
The %v verb can be used to print the error chain without wrapping the error (e.g., fmt.Errorf("internal failure: %v", err)).

`Is` and `As`

Use errors.Is to check for specific errors.
Use errors.As to check for specific errors and get the underlying error.
errors.As can take as the second parameter a pointer to a variable of the type of the error we are looking for, but just as well it can take a pointer to an interface.

Wrapping Errors with defer

Using named return values and defer can make error handling easier because the error can be formatted only once at the end of the function.

Panic and recover

A panic is used to indicate that the program cannot continue (e.g., out of memory error or trying to read beyond the end of a slice).
When a panic occurs, the program stops executing and the stack is unwound, running all deferred functions until the main function is reached.
panic and recover are not intended to be used for error handling.
It is better to explicitly handle errors than to use panic and recover because it is not clear when calling recover what failed exactly.

Getting a Stack Trace from an Error

Go doesn’t provide a stack trace by default outside of a panic state.
%+v can be used to print the stack trace with fmt.Printf.
Pass the -trimpath flag to go build to remove the absolute path from the stack trace, which otherwise shows full paths to files.

Modules, Packages, and Imports

The module is the root of the package tree. It can be defined in go.mod or inferred from the directory structure. For a GitHub repository, it is inferred from the URL as in module github.com/{USER}/{PROJECT}.
Keep a single module per repository.

`go.mod`

Use go mod init MODULE_PATH to create a new module (go.mod file).
The module path is case-sensitive.
The minimum version of Go required to build the module can be specified with go mod init MODULE_PATH GO_VERSION and it appears in the go.mod file below the module declaration.
There can be a require directive for each dependency.
There are also two optional sections: replace and exclude.
- replace is used to replace a dependency with a local version.
- exclude is used to exclude a dependency from the build.

 go
 
 
 
// Example of a go.mod file
module github.com/{USER}/{PROJECT}

go 1.xx

require (
 github.com/{OTHER_USER}/{OTHER_PROJECT} v0.0.0-20200921021027-5abc380940ae
 github.com/shopspring/decimal v1.2.0
)

Building packages

Imports and exports

Import statements allow accessing exported constants, variables, functions and types from another package.
An exported identifier starts with a capital letter. It cannot be accessed from another package without an import statement.

Creating and accessing packages

The first line of the file should be package {PACKAGE_NAME}. It’s a package clause.
Next is the import section.
- Importing from the standard library doesn’t require a path.
- Any other imports require a path, using the module path as a prefix and appending the path to the package.
- Not using any identifier from a path will result in a compiler error. Hence, all code included in the build will be used.
- It is best to always use absolute paths for clarity.
- The name of a package is determined by its package clause, not by the path being imported. In general, the package name should match the last element of the path.
- The main package cannot be imported as it is the entrypoint of the application.
Package names are in the file block: the package name is the same for all files in the same directory and must be present.

Naming packages

The package name should be descriptive.
Avoid util and common packages. Create more packages with fewer functions instead.
Don’t include the name of the package in functions, as this will be disambiguated by the package name when importing.

Organizing a module

There is no official structure.
The cmd directory is used for executables. There can be multiple executables produced by different applications from a module.
When there are a bunch of files at the root to manage deployment and testing, it is a good pattern to put all packages inside a pkg directory.
- Inside pkg, limit dependencies between packages by organizing the code according to the functionality it provides.
- A good primer on the topic is GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps.

Overriding a package’s name

When names collide, you can use an alias to rename a package.
- In the standard library, both "crypto/rand" and "math/rand" are imported as "rand", but they can be disambiguated with an alias such as crand "crypto/rand".
Using the . alias is discouraged because it makes it harder to understand where a function is coming from as it will import all exported identifiers from the current namespace (same idea as import * from ... in Python).
Package names can be shadowed, which renders it inaccessible. Always resolve conflicts by using an alias instead.

Package comments and `godoc`

Comments must be placed right above the item to be documented.
Comments start with // and can be multiline.
A blank line with // is used to create paragraphs.
Preformatted text can be inserted with indentation.
Comments before the package clause create package-level documentation.
- If the package has a lot of documentation, it is better to put it in a separate file called doc.go.
Comments should start with the name of the item being documented.

Internal package

Use the internal directory to create packages that are only accessible from the parent and sibling packages.
Trying to access an internal package from outside the module will result in a compiler error.

The `init` function

If there is an init function in a package, it runs as soon as the package is referenced by another package.
It has not input or output parameters and can only cause side-effects within the package.
There can be multiple init functions in a package, even in the same file, although this setup is discouraged.
A blank import can be used to run the init function of a package without using any of its exported identifiers, e.g., import _ "github.com/lib/pq". Explicit is better than implicit: this is an obsolete pattern.

Circular dependencies

They are not allowed to keep the code readable and the compiler fast.
If two packages depend on each other, they should probably be merged into a single package.
If two packages with circular dependencies are still preferred, it may be possible to move only the culprits into a separate package so that both packages can import them.

API renaming and organizing

To avoid breaking a function name, a new method can be added with the new name, calling the old one.
Constants can be re-declared with the same types, but with a different name.
To rename exported types, we can create an alias such as type Bar = Foo. In this case, new methods should still be added to the original type to preserve backward compatibility.
Caution: a field name cannot be changed without breaking backward compatibility.

Working with modules

Importing third-party code

go.mod is used to manage dependencies.
go.mod is automatically populated when a go command runs and a dependency is required (e.g., go build, go list, go run, go test).
go.sum is used to verify the integrity of the dependencies.
god.mod and go.sum should both be committed to version control.

Working with versions

go list is used to list dependencies used by a project.
- By default, it lists packages used.
- The -m flag is used to list modules used.
- Appending the -versions flag to the previous command lists all versions of the dependencies.
go get can be used to downgrade or upgrade a dependency (e.g., go get github.com/{USER}/{PROJECT}@v1.0.0).
- It can also be used to add a new dependency.
- It can be used to remove a dependency by adding the -u flag.
- Changes will be reflected in go.mod and go.sum.
Dependencies might be shown with // indirect next to them. This means that the dependency is not used directly by the project, but by one of its dependencies.
- It can be added when the project uses that dependency directly with a newer version than what is declared in the dependency’s go.mod file.
Go follows semantic versioning (SemVer).
There is an import compatibility rule: all minor and patch versions should remain compatible and if not, this is considered a bug.
- Instead of importing multiple versions of the same library as with npm, Go will import the highest version of the library that satisfies the requirements.

Updating to compatible versions

Use go get -u=patch DEPENDENCY_PATH to update to the latest compatible patch version.
go get -u DEPENDENCY_PATH will update to the most recent compatible version.

Updating to incompatible versions

Go follows the semantic import versioning rule: for all major versions greater than 1, the major version is included in the import path, e.g., "github.com/{USER}/{PROJECT}/v2".
Once a new major version is used in the project, go build will update the go.mod file to use the new major version.
Older versions may still be present in go.mod: go mod tidy can be used to remove them.

Vendoring

go mod vendor is used to create a vendor directory with all the dependencies to ensure reproducible builds.
It dramatically increases the size of the project in version control.

`pkg.go.dev`

It automatically indexes Go projects.
It is used to search for packages and their documentation.
It publishes the godocs, license, README, the module’s dependencies and which other open source projects depend on it.

Publishing modules

Go favors permissive licenses (e.g., MIT, BSD, Apache).
There is no need for a central repository, as Go uses the module path to find the module.

Versioning modules

Minor and patch versions should be compatible and are easy to manage.
Major versions are slightly more difficult to manage. For instance, let’s go from v1 to v2.
- Create a directory to put all the old code in, named v2, including README and LICENSE files.
- Create a branch.
  - Name the branch v1 if the old code goes in it.
  - Name the branch v2 if the new code goes in it.
- Make sure the module path in go.mod ends with /v2.
- Update all import paths to use the new module path.
- Create a tag for the new version.
  - Name the tag v2.0.0.
  - Tag the main branch if the new code goes in it.
  - Otherwise, tag the v2 branch.
If breaking changes might be introduced while on the new version, use a pre-release version, e.g., v2.0.0-alpha.1.
The open source project mod can be used to automate this process.
The Go Blog has a post on the topic.

Module proxy servers

Google manages a module proxy server that fetches all versions of all publicly available modules.
Google also maintains a sum database, which stores the checksums of all the modules.
Modules are only installed from the proxy server if they are not already present in the local cache and if the checksums match.

Specifying a module proxy server

The GOPROXY environment variable can be used to specify a module proxy server. To use GoCenter, set it to GOPROXY=https://gocenter.io.
If the GOPROXY environment variable is set to direct, the module proxy server will not be used and the module will be downloaded directly from the source.
Projects such as athens can be used to create a local module proxy server.

Concurrency in Go

When to use concurrency

Concurrency is not parallelism.
Concurrency is useful when there are multiple tasks that can be executed independently.
Concurrency brings benefits when a process takes a long time to complete.
Read The Art of Concurrency for more information.
The book Concurrency in Go is also a great resource.

Goroutines

“Goroutines are lightweight processes managed by the Go runtime”.
Because Go manages goroutines, they are cheap to create and destroy (no need to create system-level resources).
They are memory efficient because they are allocated on the stack with small initial sizes.
Switching between goroutines is fast because it is managed by the Go runtime within a process.
Go optimizes how work is distributed across goroutines.
- For more details on this, watch GopherCon 2018: Kavya Joshi - The Scheduler Saga.
A goroutine starts by calling a function with the go keyword in front of it.

Channels

Channels are used to communicate between goroutines.
They are a built-in type that require the make function to create them, e.g., ch := make(chan int).
The zero value of a channel is nil.
They are passed as parameters to functions as a pointer.

Reading, writing, buffering

The <- operator is used to send and receive data from a channel. It indicates the direction of the data flow.
A function parameter can specify the direction of the channel, e.g., func f(ch <-chan int) will make it so that the channel can only be read from. Likewise, func f(ch chan<- int) will make it so that the channel can only be written to.
By default, channels are unbuffered, meaning that they can only hold one value at a time. They should be used most of the time.
A channel can be buffered by specifying the buffer size when creating it. E.g., ch := make(chan int, 10).
len(ch) is used to get the number of elements in the channel.
cap(ch) is used to get the capacity of the channel.
The capacity of a channel cannot be changed after it is created.

`for-range` and channels

for-range can be used to read from a channel until it is closed, or until a break or return statement is encountered.
There is a single variable declared for the channel, which is the value read from the channel.

 go
 
for v:= range ch {
 fmt.Println(v)
}

Closing a channel

Close a channel with close(ch).
Writing to a closed channel will result in a runtime panic.
Attempting to read from a closed unbuffered channel will return the zero value of the channel’s type.
Reading from a closed buffered channel will return the remaining values in the channel until it is empty, then it will return the zero value of the channel’s type.
To know if a channel is closed, use the second return value of the receive operation with the comma ok idiom, e.g., v, ok := <-ch.
- ok will be true if the channel is open and false if it is closed.

How channels behave

They pause the execution of the goroutine until a value is available to read from the channel.
They pause the execution of the goroutine until a value can be written to the channel.
A panic will occur if a value is written to a closed channel or when trying to close a closed channel or a nil channel.
Make the writer responsible for closing the channel.

`select`

Starvation is when a goroutine is waiting for a resource that is never available.
It looks very similar to a switch statement.
A case in a select statement is executed when the channel is ready to be read from or written to.
If multiple case statements are ready, one is chosen at random – with switch, the first match is always chosen. This solves the starvation problem since all cases are checked at once.
select also deals with deadlock issues: if all channels are blocked, it will execute the default case.
select is often used in a loop to keep reading from a channel until it is closed.
- Having a default case inside a loop for a select is most certainly not what is intended as it will run constantly.

Concurrency practices and patterns

Keep APIs concurrency-free

Never expose channels or mutexes in an API. If a channel is exposed, the user will have to manage it, know whether it is buffered or not, closed or not or nil. The user could also trigger deadlocks.

Goroutines, for loops, and varying variables

Instead of shadowing variables in a for loop, pass them as parameters to the goroutine.

 go
 
 
 
// Don't do this
for _, v := range a {
 v := v // shadowing
 go func() {
 ch <- v * 2
 }()
}

// Do this instead
for _, v := range a {
 go func(val int) { // value captured by the closure
 ch <- val * 2
 }(v)
}

Always clean up your goroutines

If a goroutine is not cleaned up, it will keep running until the program exits: this is called a “goroutine leak”.

“Done channel pattern”

If multiple goroutines are running, it is useful to have a way to signal them to stop.
A channel (named done) can be used to signal the goroutines to stop.

Using a cancel function to terminate a goroutine

A cancel function can be used to terminate a goroutine.
It is a function that performs a cleanup and closes a channel.

When to use buffered and unbuffered channels

Buffered channels are useful when limiting the number of goroutines that can access a resource at the same time, when limiting the amount of work that gets queued up or when the number of goroutines is known.
Buffered channels are good to gather results from multiple goroutines when a deterministic order is not required.

Backpressure

Backpressure is a way to signal to a goroutine that it should slow down.
It is implemented with buffered channels.

Turning off a case in a `select`

Setting a variable’s channel to nil will turn off the case in a select statement.

 go
 
 
 
for {
 select {
 case v, ok := <-in:
 if !ok {
 in = nil // kills the case
 continue
 }
 fmt.Println(v)
 // ... other cases ...
 case <-done:
 return
 }
}

Time out code

Use time.After to time out code.

 go
 
 
 
select {
// this requires context cancellation to free up resources
// if the function is not finished before the timeout,
// else it will keep processing in the background
case v := <-ch:
 fmt.Println(v)
case <-time.After(1 * time.Second):
 fmt.Println("timed out")
}

Using `WaitGroups`

The done channel pattern works well when waiting for a single goroutine to finish.
When waiting for multiple goroutines to finish, use a sync.WaitGroup.
Add is used to add a goroutine to the wait group.
Done is used to signal that a goroutine is done.
Wait is used to wait for all goroutines to finish.
Use them when some cleanup is required after all goroutines are done.
ErrGroup can be used to wait for multiple goroutines to finish and return an error if one of them fails.

 go
 
 
 
func main() {
 var wg sync.WaitGroup
 var a = []int{1, 2, 3, 4, 5}
 wg.Add(len(a))
 ch := make(chan int, len(a))
 for _, v := range a {
 // The wait group is passed with a closure
 // Otherwise it would need to be passed as a pointer
 // So all goroutines share the same instance
 go func(val int) {
 defer wg.Done() // called even if panic
 ch <- val * 2
 }(v)
 }
 wg.Wait()
 close(ch)
 for v := range ch {
 fmt.Println(v)
 }
}

Running code exactly once

once.Do is used to run code exactly once.
It can be found in the sync package.
It needn’t be initialized, as the zero value is usable.
It is best to use the minimum amount of concurrency possible.

 go
 
 
 
var once sync.Once

func main() {
 once.Do(func() {
 fmt.Println("Only once")
 })
 once.Do(func() {
 fmt.Println("Only once") // will not be printed
 })
}

When to use mutexes instead of channels

Mutex stands for mutual exclusion.
Mutexes limit access to a resource to a single goroutine at a time with a locking mechanism (Lock and Unlock, which must be used carefully to avoid creating deadlocks, especially in functions implemented recursively).
They require to do more bookkeeping than channels.
They should never be copied, just like sync.WaitGroup and sync.Once.
Use mutexes when there is a shared resource that needs to be protected, such as a field in a struct.
RWMutex is used when there are multiple readers and a single writer. The critical section is protected by a write lock, while the read lock is used to read the resource by multiple goroutines.
Sometimes, performance issues with channels can be solved by using mutexes instead.

Atomics

Atomics are used to perform atomic operations on integers and pointers.
They are more niche than mutexes and channels and as such, they are not covered in this introductory summary on Go.

The Standard Library

It is battery-included, just like Python.

`io` and Friends

io is used to read (io.Reader) and write (io.Writer) data.
io.Closer is used to close a resource.
Read (io.ReaderAt) and write (io.WriterAt) data at a specific offset.
io.Seeker is used to seek to a specific offset.
There are other combinations to define more explicitly the code’s intent (ReadWriter, ReadCloser, WriteCloser, ReadWriteCloser, ReadSeeker, WriteSeeker, ReadWriteSeeker).
The io package is a great example of the power of interfaces through simple abstractions.
Reader, Writer, and Scanner from the bufio package are used to read and write data more efficiently on larger datasets.

`time`

time is used to work with dates and times.
time.Time is used to represent a date and time. It includes the usual constants for days of the week, months, etc.
time.Duration is used to represent a duration.
time.Parse is used to parse a string into a time.Time value.
time.Format is used to format a time.Time value into a string.
time.Now is used to get the current time.
time.Sleep is used to pause the execution of a goroutine for a specified duration.
time.After is used to create a channel that will receive a value after a specified duration.
time.Tick is used to create a channel that will receive a value at regular intervals.
time.Timer is used to create a timer that will send a value on a channel after a specified duration.
time.Ticker is used to create a ticker that will send a value on a channel at regular intervals.
time.NewTicker is used to create a new ticker.
time.NewTimer is used to create a new timer.
time.Since is used to get the time elapsed since a specified time.
time.Until is used to get the time until a specified time.
time.AfterFunc is used to execute a function after a specified duration.
Use Equal to compare two time.Time values.

Monotonic time

Go uses a monotonic clock to measure time.
A monotonic clock is a clock that counts up from the start of the computer.

Timers and timeouts

Use time.NewTicker to create a ticker that will send a value on a channel at regular intervals.
Use time.NewTimer instead of time.Tick, as it can be stopped and reset.

Encoding and JSON

“Marshalling” is the process of converting a data structure into a byte stream.
“Unmarshalling” is the process of converting a byte stream into a data structure.

Use struct tags to add metadata

Struct tags are strings written inside backticks that can be added to struct fields to add metadata.
They can span only one line, taking the format `tagName:"tagValue"`.
go vet can be used to check for struct tags validity.
If no struct tag is specified, the field name will be used instead.
Use a - (dash) for a field name to ignore it.
,omitempty can be added right after the field name to omit a field if it is empty.
While annotations can make the code more declarative and short, they can also make it harder to read and understand. Go for readability first.

Unmarshalling and marshalling

json.Unmarshal is used to unmarshal a JSON byte stream into a data structure.
json.Marshal is used to marshal a data structure into a JSON byte stream.

JSON, readers, and writers

json.Decoder is used to decode a JSON byte stream into a data structure.
json.Encoder is used to encode a data structure into a JSON byte stream (e.g., encoding a file given an interface: json.NewEncoder(tmpFile).Encode(toFile)).
json.NewDecoder is used to create a new decoder (e.g., decoding a file given an interface: json.NewDecoder(tmpFile2).Decode(&fromFile)).
json.NewEncoder is used to create a new encoder.

Encoding and Decoding JSON Streams

json.Decoder and json.Encoder can be used to encode and decode JSON streams.

Custom JSON Parsing

json.Unmarshaler is used to implement custom JSON parsing.
json.Marshaler is used to implement custom JSON marshalling.

`net/http`

As a modern language, Go has a built-in HTTP client and server.
Third-party libraries of interest in this space include chi and Gorilla Mux for routing needs and alice to deal with middleware chaining.

Client

Don’t use the default client in production.
Don’t use the functions to make HTTP requests directly in production as they don’t have timeouts.

Server

http.ListenAndServe is used to start a server.
The middleware pattern is used to add functionality to a server, so as to check for authentication, logging, etc.

The Context

Context is not a new feature: it is an instance that meets the context.Context interface and gets passed around as the first argument to functions, which is usually named ctx.
context.TODO is used when a context is required but there is no context available. It shouldn’t be used in production.

Cancellation

context.WithCancel is used to create a context that can be cancelled.
When a cancellable context is created, a cancel function is returned. It is used to cancel the context and it must be called (at least once) using defer.

Timers

A server can do a few things to manage its load:

It can limit the number of concurrent requests it accepts.
- It can be done by limiting the number of goroutines.
It can limit the number of requests queued up.
- This can be handled with a buffered channel.
Limit the amount of time a request can take.
- The context can be used to do this.
- context.WithTimeout is used to create a context that will be cancelled after a specified duration.
- context.WithDeadline is used to create a context that will be cancelled at a specified time.
Limit the resources a request can use (memory, disk space…).
- There is no built-in solution for this in Go.

Values

context.WithValue is used to create a context with a value.

Writing Tests

Basics of testing

The testing package is used to write tests.
go test is used to run tests and generate reports.
Tests are located in files with the suffix _test.go in the same package as the code being tested, so they have access to unexported identifiers.
Test functions start with Test and take a *testing.T parameter. They do not return any value.
The test function name should be descriptive. It can start with Test_ to indicate the function under test is unexported.

Reporting failure

Use t.Error or t.Errorf to report a failure and continue the test. Use it to conveniently report as many failures as possible.
Use t.Fatal or t.Fatalf to report a failure and stop the test. Use it when subsequent tests on the same function will fail or trigger a panic.
Use t.Log to log information about the test.

Setting up and tearing down

TestMain is used to set up and tear down tests.
- It is called once before and after all tests, not between each test.
- Can be used to set up and tear down a database, for instance.
- It can be used when package-level variables need to be initialized, although this probably means the code needs refactoring.
- It takes a *testing.M parameter. Setup can be done at the beginning, then exitVal := m.Run() is called to run tests, then teardown can be done at the end, returning the exit value with os.Exit(exitVal).
Individual test functions receive a *testing.T parameter, which has a Cleanup method that can be used to clean up after a test.
- The Cleanup method is similar to the defer statement but can be useful is the cleanup actions are performed for multiple tests from a helper function.

Storing sample test data

A directory named testdata can be created to store sample test data for the package under test, as the package directory is used for the currently working directory.
Each package accesses its own testdata directory, so it is possible to have multiple testdata directories in a project: up to one per package.

Caching test results

go test caches test results to speed up subsequent runs.
Tests recompile if the source code or the data in testdata changes.
go test -count=1 can be used to disable caching.

Testing your public API

Create a directory packagename_test to test the public API of a package, to be found at the same directory level as packagename.
Test files in this case will be named packagename_public_test.go.
Test your public API, not your implementation.
This is used to test the exported functions and methods, not the unexported ones.

Use go-cmp to compare test results

It will output the differences between the expected and actual values in a human-readable format.
It can be used to compare for strict equality as well as with custom comparators.

Table tests

Table tests are used to test a function with multiple inputs and outputs.
Table-driven tests are idiomatic in Go.
A slice of an anonymous struct is used to store the test cases.
The test function iterates over the test cases and runs the test for each of them.

Given the following:

 go
 
 
 
package adder

import (
 "testing"
)

func Add(a, b int) int {
 return a + b
}

func TestAdd(t *testing.T) {
 // Table of test cases
 tests := []struct {
 name string
 a, b int
 expected int
 }{
 {"Positive integers", 1, 2, 3},
 {"Negative integers", -1, -1, -2},
 {"Two zeros", 0, 0, 0},
 {"Negative and positive", -1, 1, 0},
 {"Two large integers", 100, 200, 300},
 }

 for _, test := range tests {
 t.Run(test.name, func(t *testing.T) {
 result := Add(test.a, test.b)
 if result != test.expected {
 t.Errorf("Add(%d, %d) = %d; want %d", test.a, test.b, result, test.expected)
 }
 })
 }
}

The output would look like this:

 
 
 
=== RUN TestAdd
=== RUN TestAdd/Positive_integers
--- PASS: TestAdd/Positive_integers (0.00s)
=== RUN TestAdd/Negative_integers
--- PASS: TestAdd/Negative_integers (0.00s)
=== RUN TestAdd/Two_zeros
--- PASS: TestAdd/Two_zeros (0.00s)
=== RUN TestAdd/Negative_and_positive
--- PASS: TestAdd/Negative_and_positive (0.00s)
=== RUN TestAdd/Two_large_integers
--- PASS: TestAdd/Two_large_integers (0.00s)
--- PASS: TestAdd (0.00s)
PASS
ok github.com/{USER}/{PROJECT}/adder 0.368s

Checking code coverage

The -cover flag can be used to check code coverage.
go test -coverprofile=coverage.out is used to generate a coverage profile.
Go ships with a very cool tool to visualize the coverage profile: go tool cover -html=coverage.out.

Benchmarks

The built-in testing framework can be used to write benchmarks.
Benchmarks are functions that start with Benchmark and take a *testing.B parameter.
See Profiling Go programs with pprof for more information on profiling Go programs.

Stubs

We can using function types and interfaces to create stubs.
A test function can implement an interface and be passed to the function under test.
A stub can be defined as a struct that implements the interface and has a field for each method of the interface. E.g., type MathSolverStub struct {}.
When testing larger interfaces, one can define a stub that implements only the methods required for the test.
For mocks, use a mocking library such as gomock or testify.

`httptest`

httptest is used to test HTTP servers without having to start them.
A complete, real-world example is provided in the test_examples repo.

Integration tests and build tags

Integration tests are used to test the interaction between multiple components.
A build tag is a comment that starts with // +build and is followed by a tag name, found on the first line of a file.
Files with no build tags are included in all builds.
If a file has a build tag like // +build integration, then it can be run with go test -tags=integration -v ./....
To skip tests that take a long time to run, use t.Skip.

 go
 
 
 
func TestFileLen(t *testing.T) {
 if testing.Short() {
 b.Skip("skipping test in short mode.")
 }
 // ...
}

// Skip it when testing in short mode
// go test -short -v ./...

Finding concurrency problems with the race checker

A data race is still possible in Go with its built-in concurrency features if a lock hasn’t been acquired.
Go comes with a race checker for just these cases: go test -race.
Adding “sleep” statements is definitely not the correct approach.
The race checker can also run after building a binary: go build -race. This is useful to detect race condition issues for code that is not covered by tests.
Note that the race checker makes the code about 10 times slower, so use it only when needed.

Here There Be Dragons: Reflect, Unsafe, and Cgo

Theses features are not used that often, but they are useful to know about.
You cannot make make methods with reflection.
It should only be used when there is no other way to do it.
It may increase maintenance cost, because crashes can happen in production due to the lack of type safety (Java cough Script cough).
This summary will only cover their starting point.

Reflection to work with types at runtime

This can be used to work with data that didn’t exist at compile time.
Use cases:
- Reading and writing from a database;
- Template engines;
- fmt uses it heavily;
- errors uses it to implement errors.Is and errors.As;
- sort uses it to sort slices of arbitrary types;
- Marshalling/unmarshalling JSON and XML;
- Comparing maps or slices for deep equality with reflect.DeepEqual.

Types, kinds, and values

A type is a description of a value’s structure and behavior.
A kind is a description of a type’s behavior.
A value is a representation of a type’s behavior.
A type can have multiple kinds.
A value can have multiple types.
reflect.TypeOf is used to get the type of a value.
reflect.Type is used to represent a type.

Making new values

reflect.New is used to create a new value of a type (reflect.Type as input, reflect.Value as output).

Use reflection to check if an interface’s value is `nil`

IsValid is used to check if a value is valid (e.g., iv := reflect.ValueOf(i), iv.IsValid(), iv.IsNil()).

Use reflection to write a data marshaler

reflect.ValueOf is used to get the value of a field.
reflect.Type is used to get the type of a field.
reflect.StructField is used to get the field’s metadata.
reflect.StructTag is used to get the struct tag.
There is a complete example of a CSV data marshaler on the Go Playground.

Build functions with reflection to automate repetitive tasks

reflect.MakeFunc is used to create a function.
reflect.ValueOf is used to get the value of a function.
reflect.TypeOf is used to get the type of a function.
Reflection makes the program slower.

You can build structs with reflection, but don’t

reflect.StructOf is used to create a struct.

`unsafe`… is unsafe

It allows manipulating memory directly.
Sizeof is used to get the size of a type (“returns how many bytes it uses”).
Offsetof is used to get the offset of a field (“returns the number of bytes from the start of the struct to the start of the field”).
Alignof is used to get the alignment of a field (“returns the byte alignment it requires”).
unsafe.Pointer is used to convert a pointer to a pointer of a different type. Pointer arithmetic is possible just like in C or C++.

Use unsafe to convert external binary data

unsafe is used to convert external binary data.
It can be use to gain performance when interacting with the system.
It can speed up marshalling and unmarshalling (about twice as fast for simple structs).

unsafe strings and slices

reflect.StringHeader is used to get the header of a string.

`cgo` is for integration, not performance

It is best used to integrate with C libraries.
cgo is the FFI (foreign function interface) of Go.
You can call C functions from Go… and even Go functions from C!
Garbage collection makes it hard to use cgo for performance.
Only use it when there’s no suitable Go library available.

A Look at the Future: Generics in Go

Go doesn’t convert types implicitly.
For a gentle introduction to the topic, there is Tutorial: Getting started with generics.

Generics reduce repetitive code and increase type safety

Generics are akin to “type parameters”.
Without generics, Go has to use interface{} and type assertions.
any is used to represent any type.
Generics allow specifying the type of a generic function’s parameters, such as func Sum[T any](a, b T) T { return a + b }.

Use type lists to specify operators

A “type list” is a list of types.

 go
 
 
 
type BuiltInOrdered interface {
 type string, int, int8, int16, int32, int64, float32, float64,
 uint, uint8, uint16, uint32, uint64, uintptr
}

Salient takeaways

Go is a practical language, valuing clarity of intent and readability (e.g., standard formatting is mandatory). It takes the best of other languages and leaves out the rest.
Comprehensibility and explicitness is more important than conciseness in idiomatic Go.
Go is “call by value”, meaning it makes copies of function parameters before passing them along.
Deployment is a breeze: a single binary file.
Go doesn’t have classes nor inheritance, but it has structs and interfaces.
Professionals use error handling profusely to make their programs more robust.

Conclusion

This book achieves its goal of teaching readers how to write idiomatic Go code that leverages the strengths of the language. It focuses on real-world examples and best practices to structure Go code, rather than just explaining language syntax. The book covers a wide range of topics including primitive types, control structures, composite types like arrays and maps, concurrency, reflection, testing, and more.

We covered the key takeaways from each chapter, providing a broad overview of important concepts. While not a replacement for reading the book in its entirety, this summary may serve as a helpful reference guide on the subject. Whether you are just starting with Go or are looking to improve your skills, Learning Go is an invaluable resource and I highly recommend it!

Resources and references

Articles

Evaluating code complexity triggers, use of complexity measures and the influence of code complexity on maintenance time, Springer
Go Modules: v2 and Beyond, go.dev
Go Release History, go.dev
Marshalling, Wikipedia
Profiling Go programs with pprof, Julia Evans

Books

Concurrency in Go, Katherine Cox-Buday, O’Reilly
Learning Go, Jon Bodner, O’Reilly
The Art of Concurrency, Clay Breshears, O’Reilly
The Go Programming Language, Alan A. A. Donovan and Brian W. Kernighan, Addison-Wesley Professional

Documentation

atof.go, cs.opensource.google
builtin documentation, pkg.go.dev
CodeReviewComments, GitHub
Effective Go, go.dev
ErrGroup, pkg.go.dev
Go By Example, gobyexample.com
Go Wiki, GitHub
How to Write Go Code, go.dev
Standard library documentation, pkg.go.dev
The Go Programming Language Specification, go.dev

Other open source projects referenced

Alice, GitHub
Chi, GitHub
go-cmp, GitHub
Gorilla Mux, GitHub
Learning Go: Code examples, GitHub
Mod, GitHub

Testing

gomock, GitHub
Profiling Go programs with pprof, Julia Evans
test_examples repo, GitHub
testing package, pkg.go.dev
testify, GitHub

Videos

GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps, YouTube
GopherCon 2018: Kavya Joshi - The Scheduler Saga, YouTube

sglavoie.com – Tag: Go

Book summary: 100 Go Mistakes and How to Avoid Them

Go: Simple to learn but hard to master

Go outline

Simple doesn’t mean easy

100 Go mistakes

Code and project organization

1 - Unintended variable shadowing

2 - Unnecessary nested code

3 - Misusing init functions

4 - Overusing getters and setters

5 - Interface pollution

6 - Interface on the producer side

7 - Returning interfaces

8 - any says nothing

9 - Being confused about when to use generics

10 - Not being aware of the possible problems with type embedding

11 - Not using the functional options pattern

12 - Project misorganization

13 - Creating utility packages

14 - Ignoring package name collisions

15 - Missing code documentation

16 - Not using linters

Data types

17 - Creating confusion with octal literals

18 - Neglecting integer overflows

19 - Not understanding floating points

20 - Not understanding slice length and capacity

21 - Inefficient slice initialization

22 - Being confused about nil vs. empty slices

23 - Not properly checking if a slice is empty

24 - Not making slice copies correctly

25 - Unexpected side effects using slice append

26 - Slices and memory leaks

27 - Inefficient map initialization

28 - Maps and memory leaks

29 - Comparing values incorrectly

Control structures

30 - Ignoring the fact that elements are copied in range loops

31 - Ignoring how arguments are evaluated in range loops

32 - Ignoring the impact of using pointer elements in range loops

33 - Making wrong assumptions during map iterations

34 - Ignoring how the break statement works

35 - Using defer inside a loop

Strings

36 - Not understanding the concept of a rune

37 - Inaccurate string iteration

38 - Misusing trim functions

39 - Under-optimized string concatenation

40 - Useless string conversions

41 - Substrings and memory leaks

Functions and methods

42 - Not knowing which type of receiver to use

43 - Never using named result parameters

44 - Unintended side effects with named result parameters

45 - Returning a nil receiver

46 - Using a filename as a function input

47 - Ignoring how defer arguments and receivers are evaluated

Error management

48 - Panicking

49 - Ignoring when to wrap an error

50 - Checking an error type inaccurately

51 - Checking an error value inaccurately

52 - Handling an error twice

53 - Not handling an error

54 - Not handling defer errors

Concurrency: Foundations

55 - Mixing up concurrency and parallelism

56 - Thinking concurrency is always faster

57 - Being puzzled about when to use channels or mutexes

58 - Not understanding race problems

59 - Not understanding the concurrency impacts of a workload type

60 - Misunderstanding Go contexts

Concurrency: Practice

61 - Propagating an inappropriate context

62 - Starting a goroutine without knowing when to stop it

63 - Not being careful with goroutines and loop variables

64 - Expecting deterministic behavior using select and channels

65 - Not using notification channels

66 - Not using nil channels

8 - `any` says nothing

25 - Unexpected side effects using slice `append`

35 - Using `defer` inside a loop

71 - Misusing `sync.WaitGroup`

72 - Forgetting about `sync.Cond`

73 - Not using `errgroup`

76 - `time.After` and memory leaks

83 - Not enabling the `-race` flag