sglavoie.com – Tag: Best Practices

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: 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

Book summary: Refactoring UI

Sébastien Lavoie — Sat, 09 Sep 2023 17:56:00 -0600

Introduction

It covers core principles like establishing consistent systems for recurring elements such as spacing and typography.
It advises generous use of white space and thoughtful visual hierarchy.
Steps for adding depth through lighting, shadows, and layers are outlined.
Recommendations are provided for working with images and illustrations effectively.
Tips on elevating default elements and breaking conventions to avoid typical, cookie-cutter designs are included.
Studying other designers’ work and unintuitive decisions is encouraged to expand one’s skills.
The goal is to equip readers with knowledge to thoughtfully craft interfaces that appear purposefully designed without simply mimicking common graphical tropes.
By learning fundamental visual design concepts tailored to user interfaces, anyone can create clean, functional, and visually engaging digital experiences.

Starting from scratch

Start with a feature, not a layout
- Design the shell and navigation later once you know what features you need.
Detail comes later
- Design with a big sharpie.
- Design in grayscale to use spacing, contrast and size to do the heavy lifting.
Don’t over-invest
- Go with low-fidelity sketches and wireframes first to move fast. Don’t get bogged down with details like fonts and colors early on.
Don’t design too much
- Work in cycles: design a feature simply, build it, fix errors.
- Be a pessimist: expect it to be hard to build, and postpone building it (e.g., commenting system without attachments at first).

Choose a personality

Font choice
- Elegant/classic: serif
- Playful: Sans-serif
- Plain: neutral sans-serif
Color
- Blue: safe and familiar, good overall pick.
- Gold: expensive, sophisticated.
- Pink: more fun, less serious.
Border radius
- Small – neutral, not much personality.
- Large – more playful.
- None – more serious/formal.
- Stay consistent – either rounded or not, same everywhere.
Language
- Choose the right words for the desired tone.
Decide what you actually want
- Look at the websites your expected customers use? Serious, then that’s the feel. Playful? Then that.

Limit your choices

Define systems in advance
- Have a working palette color and limit yourself to it.
- Use a type scale to avoid picking specific font sizes.
Designing by process of elimination.
Systematize as much as possible to avoid repetitive low-level decisions.

Hierarchy

Visual hierarchy refers to how elements appear in importance relative to one another.
Don’t let HTML semantics dictate visual styling – style based on visual hierarchy.
Size isn’t everything. Bold font communicates importance. De-emphasize secondary/tertiary information to highlight the most important elements.
Rely on font weight and color, not just font size, to create hierarchy.
Limit yourself to 2-3 colors and font weights to define hierarchy.
On colored backgrounds, pick a color with similar hue but lower saturation/lightness rather than just making text gray.
Avoid label: value formats – use formats, context, and combined labels/values for clarity without labels.
Treat labels as secondary content when needed – smaller, lower contrast, lighter weight.
De-emphasize competing elements instead of just emphasizing the key element.
Combine labels and values: e.g., instead of “In stock: 12”, use “12 left in stock”.
Treat labels as supporting content.
Design buttons based on hierarchy, not just semantics. Primary/destructive actions don’t always need prominence.

Layout and spacing

Start with too much white space, then remove until happy – often ends up being “just enough”.
Compact layouts have their place but should be a deliberate choice, not the default.
Establish a spacing and sizing system
- A linear scale won’t work
- Create a constrained spacing/sizing system based on a base unit (like 16px) to work faster with more consistency.
Don’t feel the need to fill the whole screen – give elements only the space they need.
Grids are overrated
- Not all elements should be fluid
- Don’t shrink an element until you need to.
- Grids can bring order but don’t have to dictate every layout decision.
Balance layouts in columns instead of just making things wider.
Relative sizing doesn’t scale.
- Fix element widths when flexibility isn’t needed.
- Scale elements independently – don’t rely on relative units like em.
Avoid ambiguous spacing: increase spacing between groups and reduce spacing within groups to show relationships.

Text

Establish a constrained type scale to speed up font size decisions and add consistency. Avoid strict modular scales.
Use pixel or rem units – not em – to guarantee sizes match the scale.
For UI design, pick scale values by hand instead of using a mathematical ratio.
Use high quality fonts – safe bets are neutral sans-serifs and system fonts.
Use the system stack if not sure: -apple-system, Segoe UI, Roboto, Noto Sans, Ubuntu, Cantarell, Helvetica Neue;
Favor fonts with 5+ weights and optimized for legibility.
Keep line length between 45-75 characters (20-35 em) for optimal readability.
Align mixed font sizes by their baselines, not centers.
Use taller line-heights for small text and shorter line-heights for large text.
Subtly emphasize links in UIs, no need for high contrast colors.
Left align most text, right align numbers in tables. Justify only with hyphenation.
Don’t center long form text.
Tighten letter-spacing for headlines set in text faces. Loosen letter-spacing for all-caps.
Not all links need to be emphasized boldly, especially in UIs where there is plenty of interactivity.

Colors

HSL (hue, saturation, lightness) is more intuitive to the human eye: use it instead of HEX and RGB.
- Hue is the color position on the color wheel. 0° is red, 120° is green, and 240° is blue.
- Saturation represents the vividness. 0% is grey while 100% is vibrant and intense.
- Lightness measures how close a closer is to black (0%) or white (100%), where 50% is the pure color.
HSL is not the same as HSB (lightness != brightness). In HSB, 0% brightness is always black but 100% brightness is white when saturation is set to 0%.
- With 100% saturation in both HSL and HSB, 100% brightness is equivalent to 50% lightness (pure color).
Don’t rely solely on color to convey information - support it with other indicators.

A good color palette

You need more colors than you think - aim for 10+ shades of greys, primary colors, and accent colors.
Grey
- There is a lot of grey in UIs: between 8-10 shades of grey is a good array of options to pick from. Use very dark grey instead of true black so it looks more natural.
Primary colors
- 1 or 2 is great, with 5-10 different shades (e.g., Facebook is basically blue). A very light shade is good for a tinted background (e.g., alerts), darker shades work great for text.
Accent colors
- Use sparingly.
- Needed to bring semantic meaning, such as red for danger, yellow for warnings and green for positive trends.
- For a complex UI, can be as many as 10 different colors, each with 5-10 shades.

Building a color palette

Define color shades upfront instead of generating on the fly. Pick base, darkest, lightest, then fill in gaps.
Don’t rely purely on math to generate shades - trust your eyes and tweak if needed.
Choose the base color first. This is the color in the middle that light and dark shades are derived from.
Center: pick a shade that would work well as a button background.
Extremes: pick the lightness color to work as a background and the darkest to work on top as text to get enough contrast.
Repeat the process to pick the remaining colors in between. 9 shades is a good sweet spot as it divides cleanly.
For grays, the base color doesn’t matter nearly as much: same process.

Perceived brightness

In the HSL system, the further away a color is from 50% lightness, the more saturated it should be so it doesn’t look washed out.
The perceived brightness of a color to the human eye can be calculated as follows:

brightness = √(0.299·r² + 0.587·g² + 0.114·b²) / 255

Green is perceived as more bright than red, which in turn is perceived as more bright than blue. With this data point, we can tweak the perceived brightness of a color by rotating the color wheel towards the desired perceived brightness.
Grays aren’t usually totally desaturated.
- To make them feel “cool” saturate them with some blue.
- To make them feel “warm”, saturate them with yellow or orange.
- The same “saturation curve” applies to grays: the further away from 50% brightness, the more they should be saturated to avoid looking washed out.

A word on accessibility

Instead of having elements like dark-colored pills with a white foreground color, flip the contrast by having light-colored pills with a dark version of the color in the foreground so they won’t grab too much attention.
Rotate the hue to make the color pop more. For instance, instead of cranking up the lightness to meet ideal contrast ratios, rotate the hue and possibly keep the saturation high for a vibrant contrast.
Don’t rely on color alone
- Add visual cues (like arrows for upward/downward trends). Designing in grayscale first will help spot these kinds of issues.
- For things like a graph, playing with contrast will produce clearer results.

Depth

Mimic how light works in the real world.
- Emulate a light source coming from above to make elements appear raised or inset.
- For instance, with a button, if light comes from above, then the top should be lighter (e.g., box-shadow inset) than the bottom (box-shadow, casting shadow only below).
- For elements that are “inset” (I.e., more depth in the center), the opposite effect should happen: more light reaches the bottom part (vertical box-shadow, going up) than the top part (box-shadow inset such that it casts some shadow towards the bottom).
Don’t overdo it.

Shadows

Use shadows to convey elevation
- When something appears to be raised from the background (e.g., bigger drop-shadow), it attracts the user’s focus.
- Small shadows are useful to attract attention to the primary action to be performed.
- Medium shadows are useful for things like a dropdown so it looks separate from the background.
- Large shadows are great for modals.
- 5 options is usually plenty.
- Can be used for interactivity, like when dragging a row from a table.
- A button can feel like it’s being “pressed” by reducing its shadow on click (i.e., it gets closer to the page or farther away from the user).
- Casting shadows
  - To simulate a shadow cast by direct light (e.g., a long shadow behind a plant getting some sunlight), use a larger, more diffuse and subtle shadow.
  - To simulate a shadow cast by ambient light (e.g., the shadow right below the plant’s pot where light can’t hardly reach), use a narrow and darker shadow.
  - Apply both types of shadow casting at once to create visually compelling effects.
Define a fixed set of shadows as an elevation system for consistency.
Even flat designs can have depth
- Flat design does not convey depth with shadows and gradients.
- Create depth with color: lighter colors feel closer.
- Can use short, offset shadows with no blur at all.
Overlap elements to create layers
- E.g., position a block with a negative margin so it appears on top of two different sections.
- For smaller elements like avatars, an invisible border around it can make it pop better.

Images and contrast

Images
- Use high quality photos - hire a pro or use stock sites for generics. Don’t expect good results from phone pics.
Text needs consistent contrast
- Add an overlay to background images to get readable headlines.
- Lower the image contrast. Adjust the brightness to compensate.
- Colorize the image with a single color.
- Use text shadows instead of overlays to preserve image dynamics.

Scale

Don’t scale up icons
Even for SVGs, they will lack detail if they were designed correctly at a smaller scale: use a more detailed icon instead.
If updating the icon is not an option, enclose it inside another shape (e.g., a circle with a background color) to occupy more space.
Don’t scale down screenshots
Details will be distorted and hard to read.
Either use a presentation from a smaller device (e.g., the tablet version on a desktop) or take a partial screenshot (e.g., “zoom in” effect with a circle or simply crop the original image).
If a more complex UI needs to be presented, simplify the original image so the user doesn’t try to read a 4px font size but instead sees simpler shapes.
Don’t scale down icons
E.g. for a favicon, redraw a simplified version instead: details will look fuzzy at a small size.
User-submitted content (e.g., Instagram feed)
Control the size and shape: crop images to keep the aspect ratio of containers so they don’t disturb layout (e.g., background-size: cover).
Add inner shadows or borders to user images to prevent background bleed.

Finishing touches

Use icons instead of bullets in a bulleted list.
Play with size and colors. E.g., you can have huge quotes around the block of text representing a testimonial.
Links deserve special styling.
Use custom checkboxes and radio buttons in forms: integrate the brand’s primary color(s).
Add color with accent borders, e.g. across the top of a card element, when highlighting active elements in the UI or to the left of alert messages.
Decorate backgrounds
- Change the background color. Works great for different page sections.
- Can use gradients: use two hues that are within 30˚ of each other.
- Use repeating patterns.
Consider the empty state carefully, especially when the user is meant to fill the UI with data.
- Prioritize empty states with illustrations and clear calls to action.
- I.e., a contact page with no contacts should feel welcoming, with some icon and button to add a contact instead of a blank page with an error-like statement.
- Similarly, things like dashboard may present a bunch of options that won’t apply until there is something to show: simplify the user experience.
Use less borders
- Use box shadows, spacing, and color instead of borders to distinguish elements.
- Have two background colors for containers (e.g., darker footer that looks separate from the main content).
- Replace borders with additional spacing.
Make components more exciting
- E.g., a table may not need all its columns if a particular column does not need to be sorted and could instead be part of another one (e.g., combining a dollar amount with a plan type or a person’s name with its title).
- Radio buttons could be cards instead if they are an important part of the UI.

Next level

Look for unintuitive decisions in designs you admire to find new ideas.
Rebuild interfaces you love to discover small details that make them exceptional.
Study others to build a solid foundation.

Conclusion

The concepts covered in this book demonstrate that effective visual design does not require innate artistic talent or formal training. By approaching interfaces methodically, establishing constraints through systems for recurring elements, and learning to strategically apply principles like visual hierarchy, white space, and depth cues, anyone can create designs that appear polished and purposeful. While internalizing these fundamentals does take practice, the ideas presented remove much of the subjective, nuanced expertise needed for things like picking complementary colors or balancing composition in illustrations.

By focusing on interfaces rather than free-form graphical work, the required skills become more structured and intentional choices drive outcomes. While studying formally can provide more breadth, the core principles in this text are enough to equip non-designers with the ability to build clean, intuitive, and aesthetically pleasing digital products. By implementing the recommendations covered, engineers and others new to design can gain confidence in their interface design skills. A great, concise read!

Book summary: Effective Java

Sébastien Lavoie — Sun, 11 Jun 2023 18:15:00 -0600

Book summary

Creating and destroying objects

Item 1: Consider static factory methods instead of constructors

Use static factory methods to increase readability and make classes more flexible (e.g., Foo.withOpenBar() instead of new Foo(true)).

Item 2: Consider a builder when faced with many constructor parameters

When a class has many parameters, use a builder instead of a “telescoping constructor pattern” (i.e., having a separate method to call the class with any number of parameters, which may or may not all be used, leading to confusion and difficulty to use).
The “JavaBeans pattern” uses setters and a parameter-less constructor, allowing the use of any parameters as needed when using the code (e.g., Foo.setMethod()). This allows the class to enter in an inconsistent state (it is difficult to guarantee that a combination of used parameters makes sense) and makes it difficult to create an immutable class.
This pattern allows calling code like NutritionFacts cocaCola = new NutritionFacts.Builder(240, 8).calories(100).sodium(35).carbohydrate(27).build();, which basically instantiate a class with optional parameters as would be the case in Python.

Item 3: Enforce the singleton property with a private constructor or an enum type

The recommended path forward is to use an enum type like so:

 java
 
 
 
public enum MyClass {
 INSTANCE;
 public void myMethod() { ... }
 }

...

MyClass instance = MyClass.INSTANCE;
instance.myMethod();

Item 4: Enforce non-instantiability with a private constructor

Simply define the class constructor to be private so that the class cannot be instantiated. This is useful for utility classes that may contain a bunch of static methods where instantiating the class itself is nonsensical.

Item 5: Prefer dependency injection to hardwiring resources

The example given with a SpellChecker that depends on a Dictionary makes a lot of sense: instead of having a class SpellChecker define a Dictionary that won’t be reusable elsewhere or that may need to change, pass the Dictionary into the constructor of the class so that different dictionaries can be used with the same class, making it easier to test things independently and update an existing implementation.

Item 6: Avoid creating unnecessary objects

The author provides two striking examples of where creating unnecessary objects can be detrimental to performance: using Long sum = 0L; instead of long sum = 0L; when summing up positive integers and matching a regular expression on a string repeatedly instead of compiling the regular expression once for re-use. In short, avoid creating unnecessary objects and prefer primitives over boxed primitives.

Item 7: Eliminate obsolete object references

The author provides an example of a stack implementation that has a memory leak because the stack maintains obsolete references to objects that have been popped off the stack. The solution is to null out references once they are no longer needed, which in this case happened in a class where manual memory management was occurring. This is a problem because the garbage collector has no way of knowing that the objects it references after a certain portion of the array are no longer needed.
The author also shows an example of a cache that uses a WeakHashMap to store the cache, which allows the garbage collector to remove entries from the cache when they are no longer referenced elsewhere in the program.

Item 8: Avoid finalizers and cleaners

“Finalizers are unpredictable, often dangerous, and generally unnecessary.” They can lead to performance issues and resource leaks. They should be avoided. There is no guarantee that they will be called in a timely manner, or at all.

Item 9: Prefer try-with-resources to try-finally

The author provides an example of a class that reads the first line of a file and returns it as a string. The class uses a BufferedReader to read the file and a FileReader to open the file. The problem is that the FileReader is never closed, which can lead to resource leaks. The solution is to use a try-with-resources block, which will automatically close the FileReader when the block is exited.

Methods common to all objects

Item 10: Obey the general contract when overriding `equals`

The equals method must be reflexive, symmetric, transitive, consistent, and x.equals(null) must return false.
It is generally a bad idea to @Override the equals method when inheriting from a concrete class, as it is difficult to ensure that the contract is respected. It is better to use composition instead of inheritance in this case.

Item 11: Always override `hashCode` when you override `equals`

If two objects are equal according to the equals method, they must have the same hash code. The reverse is not true: two objects with the same hash code are not necessarily equal.
Using the AutoValue framework in Java, it is possible to automatically generate equals and hashCode methods for a class.

Item 12: Always override `toString`

The toString method should return a concise, useful description of the object. It should be overridden in every class unless the class is a utility class or a small value class.
The toString method should return all of the interesting information contained in the object when it is practical to do so. It should not return the memory address of the object.

Item 13: Override `clone` judiciously

The clone method is broken in Java. It is better to use a copy constructor or a copy factory instead of the clone method.
One exception is when a class implements the Cloneable interface and has a final field that is a reference to an array or a final field that is a reference to an object. In this case, the clone method can be used to create a copy of the object.

Item 14: Consider implementing `Comparable`

Implement the Comparable interface when a class has a natural ordering. This allows the class to be used in sorted collections and provides a way to compare objects of the class.
An example is given to compare phone numbers using the Comparable interface, where chaining happens in order to compare from the most significant field to the least significant field, e.g.:

 java
 
 
 
// Comparable with comparator construction methods
 private static final Comparator<PhoneNumber> COMPARATOR =
 comparingInt((PhoneNumber pn) -> pn.areaCode)
 .thenComparingInt(pn -> pn.prefix)
 .thenComparingInt(pn -> pn.lineNum);
 public int compareTo(PhoneNumber pn) {
 return COMPARATOR.compare(this, pn);
}

Classes and interfaces

Item 15: Minimize the accessibility of classes and members

Make each class or member as inaccessible as possible. This allows for better encapsulation and makes it easier to change the implementation of a class without breaking the code that uses it.
In public classes, instance fields should rarely be public, as that generally makes the classes themselves non-thread-safe. Instead, use accessor methods to access the fields.
Static final fields can be made public if they are immutable.

Item 16: In public classes, use accessor methods, not public fields

When a class needs to be accessed outside of its package, provide accessor methods instead of making the fields public. This allows the class to change its implementation without breaking the code that uses it.
This does not really apply to nested or private classes that are only used within the package as long as they still represent data structures usefully, as this leads to less visual clutter.

Item 17: Minimize mutability

Don’t allow the class to use mutators.
Prevent the class from being extendable.
Make all fields final.
Make all fields private.
Don’t write setters when they are not needed.
Reducing the number of states a class can find itself in makes it easier to reason about the class and reduces the number of bugs that can occur.

Item 18: Favor composition over inheritance

Inheritance is often overused and can lead to fragile code. It is better to use composition instead of inheritance where appropriate.
When a class takes a reference to another class as a parameter in its constructor while extending the interface for the class it is taking as a parameter via a forwarding class, it is using composition, as it calls super(otherClass) in its constructor. This allows the class passed as a parameter to be extended without having to change the class itself. In this way, the class using composition becomes a wrapper that can add functionality on top of the class it is wrapping. The books gives an example of a ForwardingSet that extends Set and takes a Set as a parameter in its constructor. The ForwardingSet can then add functionality on top of the Set it is wrapping, in this case by counting the number of times the add method is called.
The main, appropriate use case for inheritance is when a class is a subtype of another class and satisfies the is-a relationship.

Item 19: Design and document for inheritance or else prohibit it

To test a class for inheritance, try to extend it. If it is not possible to extend the class, it is not designed for inheritance.
No overridable methods should be called in the constructor, because the superclass runs before the subclass, and the subclass will not have been initialized yet.
It is better to prohibit inheritance by declaring a class to be final and ensuring that no constructors are accessible.

Item 20: Prefer interfaces to abstract classes

Interfaces are better than abstract classes because they allow for multiple inheritance, they allow for the creation of mixins, and they allow for the creation of tag interfaces.
Interfaces can define types that do not need to be represented hierarchically. For instance, a DirectorPhotographer interface can be created that extends both the Director and Photographer interfaces.

Item 21: Design interfaces for posterity

Multiple programmers should implement interfaces in different ways, and multiple client programs should use the interfaces to ensure they satisfy all intended uses. Flaws in interfaces are easier to correct before release.
The moral is to be cautious when adding methods to existing interfaces using default methods and to thoroughly test and design interfaces to avoid issues and flaws in the long term.

Item 22: Use interfaces only to define types

Interfaces serve as types that define what a client can do with instances of a class that implements the interface.
Constant interfaces consist solely of static final fields, exporting constants. They are a poor use of interfaces as they expose implementation details and confuse users.
- Implementing a constant interface leaks implementation details into the class’s API and creates a commitment to maintain binary compatibility. Subclasses of a class implementing a constant interface are also affected.
- If constants are tied to an existing class or interface, add them directly to that class or interface. If constants are best viewed as members of an enumerated type, use an enum type. Otherwise, use a noninstantiable utility class to export the constants.
Interfaces should be designed to define types and not used solely for the purpose of exporting constants.

Item 23: Prefer class hierarchies to tagged classes

Tagged classes are verbose, error-prone, and inefficient. They have boilerplate code, mix multiple implementations in a single class, increase memory footprint, require careful initialization, and make it difficult to add new flavors.
- Instead, abstract classes can be used as the root of the hierarchy, with concrete subclasses representing each flavor.
Class hierarchies eliminate the shortcomings of tagged classes. They are simpler, clearer, have no boilerplate, ensure field initialization, prevent missing cases, support independent extensibility, and provide distinct data types for each flavor.
- Class hierarchies can reflect natural relationships among types. For example, a square can be represented as a subclass of a rectangle in the hierarchy.

Item 24: Favor static member classes over nonstatic

There are four kinds of nested classes in Java: static member classes, nonstatic member classes (inner classes), anonymous classes, and local classes.
- Static member classes are ordinary classes declared inside another class and have access to all members of the enclosing class. They are static members of their enclosing class and serve as public helper classes. They obey the same accessibility rules as other static members.
- Nonstatic member classes are implicitly associated with an instance of the enclosing class and can access methods and fields of the enclosing instance. They require an enclosing instance to be created and cannot exist independently.
- Private static member classes are used to represent components of the object represented by their enclosing class. They don’t require access to the enclosing instance and avoid unnecessary memory usage compared to nonstatic member classes.
If a member class doesn’t require access to an enclosing instance, it should be declared as a static member class to avoid the overhead of an extra reference and potential memory leaks.
Static member classes are preferred over nonstatic member classes unless access to the enclosing instance is necessary.

Item 25: Limit source files to a single top-level class

The risks stem from the possibility of providing multiple definitions for a class, and the order in which source files are passed to the compiler determines which definition is used.
If there is a need to group related classes, consider using static member classes as an alternative. Static member classes enhance readability and allow for reduced accessibility by declaring them private.

Generics

Item 26: Don’t use raw types

Raw types are generic types used without specifying any type parameters.
Using raw types can lead to errors at runtime (the compiler doesn’t provide type safety) and should be avoided.
Instead of using raw types, it is recommended to use parameterized types to ensure type safety and expressiveness.
Unbounded wildcard types (e.g., Set<?>) can be used when the actual type parameter is unknown or doesn’t matter: they offer flexibility while still maintaining type safety.

Item 27: Eliminate unchecked warnings

Some unchecked warnings are easy to eliminate by specifying the type parameter or using the diamond operator (<>).
Treat unchecked warnings seriously and make efforts to eliminate them, ensuring type safety and reducing the potential for ClassCastException at runtime.

Item 28: Prefer lists to arrays

Arrays are covariant, which means if Sub is a subtype of Super, then the array type Sub[] is a subtype of the array type Super[]. Generics, on the other hand, are invariant.
Arrays are reified, meaning they enforce their element type at runtime, while generics use erasure, enforcing their type constraints only at compile time.
Arrays do not provide compile-time type safety, and errors may only be discovered at runtime, which is undesirable.
Generic collections should be used instead of arrays to ensure better type safety and interoperability.
Using lists instead of arrays allows for better compile-time type safety, even if it sacrifices some conciseness or performance.

Item 29: Favor generic types

The use of generic types eliminates the need for explicit casts and ensures type safety at compile time.
Bounded type parameters can be used to restrict the permissible values of type parameters in generic types, allowing for more specific behavior without explicit casting.
It is recommended to use generic types whenever possible to avoid casting and improve type safety. Existing non-generic types should be generified, making them easier to use without breaking existing clients.

Item 30: Favor generic methods

To write a generic method, add type parameters to its declaration and use those type parameters throughout the method.
Generic methods provide type safety and ease of use by eliminating the need for explicit casts.
Bounded wildcard types can be used in generic methods to make them more flexible and allow for different types of arguments.

Item 31: Use bounded wildcards to increase API flexibility

Parameterized types are invariant, meaning that List<String> is not a subtype of List<Object>.
Wildcard types allow you to specify that a parameter can be a subtype of a certain type, using ? extends Type for producers and ? super Type for consumers.
Wildcard types should not be used as return types.
Wildcard types are particularly useful when working with comparables and comparators.

Item 32: Combine generics and `varargs` judiciously

Varargs methods and generics do not interact well due to the nature of varargs creating arrays to hold the arguments.
Alternatively, using a List parameter instead of a generic varargs parameter can provide type safety, relying on the List.of method to handle a variable number of arguments. The code may be slightly more verbose and slower.

Item 33: Consider typesafe heterogeneous containers

Common uses of generics involve parameterizing the container itself, such as Set<E> and Map<K,V>, which limits the number of type parameters per container.
Runtime type safety can be achieved by checking the type relationship between the key and the instance being stored using a dynamic cast.
Bounded type tokens can be used to restrict the types that can be passed as keys by using a bounded type parameter or a bounded wildcard.

Enums and annotations

Item 34: Use enums instead of `int` constants

Some variants use String constants instead of int constants, but this approach has even more disadvantages. It can lead to errors, performance issues, and lacks type safety.
Enum types in Java are full-fledged classes and offer type safety, expressive power, and additional benefits.
Enum types consist of a fixed set of constants, each represented as an instance of the enum class. Enum constants are exported via public static final fields. Enum types are effectively final and can’t be extended or instantiated outside the declared constants.
Enum types provide compile-time type safety. If you declare a parameter or variable of an enum type, the compiler ensures that only valid enum constants can be assigned or passed as arguments.
Each enum type has its own namespace, allowing identically named constants in different enum types without conflicts.
Enum types can have methods, fields, and can implement interfaces.
Enum types have comparable performance to int constants. The space and time cost of loading and initializing enum types is usually negligible.

Item 35: Use instance fields instead of ordinals

While it’s possible to derive associated int values from the ordinal, it is strongly discouraged. Using ordinal-based calculations for associated values can lead to maintenance issues and limitations.
The recommended solution is to store associated int values in instance fields instead of deriving them from the ordinal. By assigning each enum constant a specific value in the constructor, you can avoid the pitfalls of relying on the ordinal.

Item 36: Use `EnumSet` instead of bit fields

Traditionally, if the elements of an enumerated type are used primarily in sets, the int enum pattern (Item 34) is used. Each constant is assigned a different power of 2, allowing bitwise OR operations to combine multiple constants into a set.
- It is harder to interpret a bit field when printed as a number compared to a simple int enum constant.
- There is no easy way to iterate over all the elements represented by a bit field.
- Bit fields require choosing a specific type (int or long) with a fixed width, which limits the maximum number of bits that can be used without changing the API.
EnumSet provides type safety and interoperability, just like any other set implementation.
- Built-in operations: Bulk operations like removeAll and retainAll are implemented efficiently using bitwise arithmetic.

Item 37: Use `EnumMap` instead of ordinal indexing

Ordinal indexing involves using an enum’s ordinal value as an index to access elements in an array or list. Problems:
- Using ordinals directly lacks the type safety provided by enums.
- Due to the incompatibility of arrays with generics, the program requires an unchecked cast, resulting in a compile-time warning.
- If the ordinal values change, the code breaks, and there’s no compile-time checking to ensure correct indexing.
- When using a two-dimensional array indexed by ordinals, the size of the table grows quadratically, even if some entries are null.
The EnumMap is a specialized map implementation designed to work efficiently with enum keys.
- They provide type safety, eliminating the need for unchecked casts. They also allow for cleaner code with no manual labeling of output.

Item 38: Emulate extensible enums with interfaces

Enum types in Java are not extensible by design.
The basic idea is to define an interface for the opcode type and an enum that implements this interface.
Emulating extensible enums with interfaces provides flexibility but has limitations. Implementations cannot be inherited from one enum type to another, and some code duplication may occur. Shared functionality can be encapsulated in a helper class or static helper method to reduce duplication.

Item 39: Prefer annotations to naming patterns

Annotations offer a superior alternative to naming patterns. They address the shortcomings of naming patterns by providing compile-time checking, better enforcement of usage constraints, and support for associating parameter values with program elements (e.g., @Test).
While most programmers may not need to define their own annotation types, they should use predefined annotations provided by Java and consider using annotations provided by IDEs or static analysis tools. These annotations can enhance code quality and diagnostic information.

Item 40: Consistently use the `Override` annotation

The @Override annotation is used on method declarations to indicate that the annotated method overrides a declaration in a supertype (class or interface).
Consistently using @Override protects against bugs by ensuring that overridden methods are correctly implemented. It helps catch errors where a method is intended to override a superclass method but ends up overloading it instead.
In abstract classes and interfaces, it is worth annotating all methods that are believed to override superclass or super-interface methods, regardless of their nature (concrete or abstract). This helps ensure correctness and prevents accidental additions of new methods.

Item 41: Use marker interfaces to define types

A marker interface is an interface that contains no method declarations but serves as a marker to designate a class implementing it as having a specific property. An example is the Serializable interface, which marks a class as serializable.
Marker interfaces define a type that is implemented by instances of the marked class, allowing compile-time error detection. They provide stronger type checking compared to marker annotations, which cannot define a type.
If the marker applies only to classes and interfaces, and there is a possibility of writing methods that accept only objects with the marking, a marker interface should be used. This enables compile-time type checking. If there is no need for such methods or if the marker is part of a framework heavily using annotations, a marker annotation is more appropriate.

Lambdas and streams

Item 42: Prefer lambdas to anonymous classes

Lambdas are concise expressions that can be used to create instances of functional interfaces, providing a more compact alternative to anonymous classes.
Lambdas lack names and documentation, making them less suitable for complex computations or those exceeding a few lines.
Anonymous classes are still necessary for creating instances of abstract classes or interfaces with multiple abstract methods. Lambdas cannot obtain a reference to themselves, unlike anonymous classes.

Item 43: Prefer method references to lambdas

Method references offer a more concise alternative to lambdas. They allow you to refer to a method by name instead of providing a lambda expression. This is particularly useful when the lambda expression only calls a method without any additional logic. E.g.:
- Method reference: map.merge(key, 1, Integer::sum);
- Lambda expression: service.execute(() -> action());
By using method references, you can eliminate the need to declare parameter names explicitly in the lambda expression.

Item 44: Favor the use of standard functional interfaces

Instead of using the Template Method pattern, which involves sub-classing and overriding methods, the modern approach is to provide static factories or constructors that accept function objects as parameters.
The java.util.function package provides a collection of standard functional interfaces for various use cases. When choosing a functional parameter type, it is recommended to use the standard functional interfaces instead of creating custom interfaces.
Functional interfaces should be annotated with the @FunctionalInterface annotation. This annotation serves as documentation, enforces the single abstract method requirement, and prevents accidental addition of abstract methods in the interface.
In API design, it’s important to avoid overloading methods that take different functional interfaces in the same argument position. This can create ambiguity for clients, and it’s best to design the API to prevent this situation.

Item 45: Use streams judiciously

Streams were introduced in Java 8 as a way to perform bulk operations on sequences of data elements. A stream represents a sequence of elements, and a stream pipeline consists of a source stream, intermediate operations, and a terminal operation.
The streams API provides a fluent API, allowing multiple operations to be chained together in a single expression. This enables concise and readable code.
Overusing streams can make code harder to read and maintain.
They have restrictions on accessing and modifying local variables and limited control flow capabilities.
Streams are well-suited for tasks such as transforming elements, filtering, combining elements, accumulating into collections, and searching. If a computation requires access to corresponding elements from multiple stages of the pipeline, streams might not be the best choice.

Item 46: Prefer side-effect-free functions in streams

The fundamental aspect of the streams paradigm is structuring computations as a sequence of transformations where each stage’s result is a pure function of the previous stage’s result. A pure function depends only on its input and does not have any side effects or modify any state.
When using stream operations, both intermediate and terminal, it’s important to ensure that the function objects passed to them are free of side effects. This means they should not depend on mutable state or update any state.
The correct usage of streams involves utilizing collectors, which encapsulate reduction strategies. Collectors can be used to gather elements into collections or create maps based on grouping or other criteria (e.g., toList, toSet, toMap, groupingBy).
There are parallel and concurrent variants of collectors, such as groupingByConcurrent and toConcurrentMap, which efficiently handle parallel execution and produce ConcurrentHashMap instances.

Item 47: Prefer Collection to Stream as a return type

A for loop cannot be used to iterate over a stream, and it’s not possible to add elements to a stream. This makes streams less flexible than collections.
- To enable iteration over a stream with a for-each loop, an adapter method can be created. The method converts a Stream to an Iterable, allowing for the use of for-each loops.
When designing a public API that returns a sequence, it is important to consider users who may prefer stream pipelines or for-each loops. The Collection interface, being a subtype of Iterable and providing a stream method, is often the best choice for a return type. Arrays can also be used when appropriate.

Item 48: Use caution when making streams parallel

Simply adding the parallel method to a stream pipeline does not guarantee improved performance. In some cases, it can lead to liveness failures, incorrect results, and unpredictable behavior.
Performance gains from parallelism are most significant when working with data structures like ArrayList, HashMap, HashSet, ConcurrentHashMap, arrays, int ranges, and long ranges. These data structures can be easily split into sub-ranges, enabling efficient work division among parallel threads.
Parallelization should only be used as a performance optimization.
Certain domains, such as machine learning and data processing, are well-suited for parallel speedups.

Methods

Item 49: Check parameters for validity

Clearly document the restrictions on parameter values in the method’s documentation. Enforce these restrictions by performing parameter checks at the beginning of the method body. Detecting errors as soon as possible is crucial for maintaining code integrity.
If a method fails to check its parameters, it may result in confusing exceptions, incorrect results, or compromised object states.
For public and protected methods, use the @throws tag in Javadoc to document the exception that will be thrown if a parameter value violates a restriction.
Use the Objects.requireNonNull method, introduced in Java 7, to check for null values. It is flexible and convenient, allowing you to specify your own exception detail message if desired. It returns the non-null value, enabling simultaneous null check and usage.
Nonpublic methods can use assertions to check parameters since the package author controls the method’s usage. Assertions throw AssertionError if the condition fails. Enabling assertions with the -ea flag is necessary for assertions to take effect.
While it’s important to check parameter validity, avoid imposing unnecessary restrictions on parameters. Design methods to be as general as possible, accepting a wide range of valid parameter values.

Item 50: Make defensive copies when needed

To protect against ill-behaved clients or honest mistakes, it is crucial to write robust classes that can handle unexpected behavior.
Classes that contain mutable objects can be vulnerable to attacks that exploit their mutability.
make defensive copies of each mutable parameter in the constructor. Use these copies as components of the class instance instead of the original objects. This ensures that changes to the original objects do not affect the class’s internal state.
Accessor methods that provide access to mutable internal fields should also return defensive copies of the fields.
Whenever possible, use immutable objects as components of your classes to eliminate the need for defensive copying. Immutable objects are inherently safe and can simplify your code.

Item 51: Design method signatures carefully

Choose method names carefully.
Avoid excessive convenience methods. Convenience methods are useful, but they can make the API more difficult to learn and maintain.
Limit parameter list length.
Prefer interfaces over classes for parameter types. Use interfaces to define parameters instead of specific classes whenever possible. This allows for more flexibility and enables the use of different implementations. For example, use the Map interface instead of the HashMap class to allow different Map implementations to be used.
Use enums instead of boolean parameters. Enums allow for future expansion by adding more options without changing method signatures.

Item 52: Use overloading judiciously

Overloading can lead to unexpected behavior: If overloaded methods have the same number of parameters and the same compile-time type of the arguments, the selection of the method is ambiguous.
Overloaded methods should have “radically different” parameter types.
Generics can create situations where two overloadings with different functional interfaces in the same argument position cause confusion. It’s recommended not to overload methods that take different functional interfaces in the same argument position.

Item 53: Use varargs judiciously

Varargs allow methods to accept a variable number of arguments of a specified type. They work by creating an array internally and passing the array to the method.
Use varargs when you want a method with a variable number of arguments. For example, when calculating the sum of integers or finding the minimum of a set of integers.
Declare the method to take two parameters: one normal parameter and one varargs parameter. This ensures that the method can handle both cases when at least one argument is passed and when more than one argument is passed.
Be aware that every invocation of a varargs method causes an array allocation and initialization, so consider the performance implications in performance-critical situations.
- To optimize performance while still using varargs, you can provide overloaded methods with a fixed number of parameters and a single varargs method for cases when the number of arguments exceeds a certain threshold.

Item 54: Return empty collections or arrays, not nulls

Returning null to indicate an empty collection or array is unnecessary and error-prone. It requires extra code in the client to handle the null return value and increases the risk of null pointer errors.
Instead of returning null, return empty collections or arrays. This can be achieved by creating a new instance of the appropriate collection or array type. For example, returning new ArrayList<>(cheesesInStock) will return an empty ArrayList if cheesesInStock is empty.

Item 55: Return optionals judiciously

Exceptions should be reserved for exceptional conditions, and returning null requires special-case code to handle it and increases the risk of null pointer errors.
The Optional<T> class represents an immutable container that can hold either a single non-null value of type T or nothing at all (empty). It provides a more flexible and less error-prone alternative to exceptions or null returns.
Avoid using Optional<T> for container types like collections, maps, streams, arrays, and other optionals. Return the empty container directly instead of wrapping it in an optional.

Item 56: Write doc comments for all exposed API elements

Javadoc is a utility that generates API documentation automatically from specially formatted doc comments in the source code.
Precede every exported class, interface, constructor, method, and field declaration with a doc comment. It describes the contract between the API element and its client.
Document the preconditions, post-conditions, and side effects of methods. Use the @param tag to describe parameters, @return tag for the return value (if not void), and @throws tag for exceptions thrown.
Use HTML tags in doc comments to format and structure the generated documentation.
Use {@code} tag to render code fragments in code font and to suppress processing of HTML markup and nested Javadoc tags within the code fragment.
Write summary descriptions as verb phrases for methods and constructors, and noun phrases for classes, interfaces, and fields. The first sentence becomes the summary description.
Use {@literal} tag to include HTML metacharacters in documentation, such as <, >, and &.
Document self-use patterns in classes designed for inheritance using the @implSpec tag. It describes the contract between the method and its subclass.
Package-level doc comments should be placed in package-info.java file. Similarly, module-level comments should be placed in module-info.java file.
Document thread-safety and serializability of classes.
Read the generated documentation to ensure clarity and make any necessary improvements to the doc comments.

General programming

Item 57: Minimize the scope of local variables

Declare variables where they are first used, rather than at the beginning of a block. This approach eliminates clutter and helps readers understand the purpose and type of the variable when it is used.
Avoid prematurely declaring variables outside of the block in which they are used. By doing so, you ensure that the variable’s scope begins at the appropriate point and ends when it is no longer needed.
Take advantage of the scope-limiting capabilities of for loops.
Prefer for loops over while loops when the loop variable is not needed after the loop terminates.
Minimizing the scope of local variables helps prevent copy-and-paste errors.
Consider using multiple loop variables within a for loop to avoid redundant computations. This approach can improve performance by storing the limit of the first variable in a second variable, eliminating the need for redundant computations in each iteration.
Keep methods small and focused to minimize the scope of local variables.

Item 58: Prefer `for-each` loops to traditional `for` loops

Traditional for loops for iteration over collections and arrays can be cluttered and prone to errors. They require explicit use of an iterator or an index variable.
The for-each loop (enhanced for statement) solves these issues by eliminating the need for explicit iterators or index variables: for (Element e : elements) { ... }
For-each loops can be used with both collections and arrays, making it easy to switch the implementation type of a container without changing the loop syntax.
For nested iteration, for-each loops offer greater clarity and simplicity compared to traditional for loops. They avoid common bugs that can occur when using multiple iterators or index variables.
There are certain situations where for-each loops cannot be used, such as when performing destructive filtering, transforming values, or iterating in parallel. In these cases, traditional for loops or other approaches may be necessary.
The Iterable interface allows objects to be iterated over using the for-each loop. By implementing the Iterable interface and providing an iterator method, your custom types can be used with for-each loops.

Item 59: Know and use the libraries

Libraries, such as Random, offer well-designed and thoroughly tested methods for common tasks.
The use of libraries saves time and effort. You can focus on your application logic instead of spending time on low-level implementations.
Standard libraries tend to improve over time in terms of performance and functionality.
While the libraries are extensive, every programmer should be familiar with the basics of java.lang, java.util, java.io, and their sub-packages. Additional knowledge can be acquired on an as-needed basis.
Certain libraries, such as the collections framework, streams library, and concurrency utilities in java.util.concurrent, should be part of every programmer’s toolkit.
Avoid reinventing the wheel. If a common task can be accomplished using existing library facilities, utilize them instead of writing your own code. Library code is often more robust and undergoes more scrutiny than individual developers can afford.

Item 60: Avoid float and double if exact answers are required

float and double types are designed for scientific and engineering calculations and provide fast but approximate results using binary floating-point arithmetic.
The inherent imprecision of float and double types makes them unsuitable for applications where exact results are necessary, such as monetary calculations.
Performing arithmetic operations with float and double types can lead to unexpected rounding errors and inaccuracies.
Rounding the results before printing is not a reliable solution to the imprecision issue.
To achieve accurate results in monetary calculations, it is recommended to use alternative data types like BigDecimal, int, or long.
BigDecimal is a precise data type that can handle exact decimal calculations. It is suitable for situations where accuracy is paramount, such as monetary calculations. However, it is less convenient to use than primitive types and slower in performance.
An alternative approach is to perform calculations in cents using int or long types, keeping track of the decimal point manually. This approach is more efficient and convenient than using BigDecimal but has limitations in handling large quantities.
Use BigDecimal when precision is critical, int or long when performance and convenience are important, and float or double when approximate results are acceptable.
BigDecimal offers full control over rounding, which is useful in business calculations with legally mandated rounding behavior.

Item 61: Prefer primitive types to boxed primitives

Java has two types: primitives (e.g., int, double, boolean) and reference types (e.g., String, List). Each primitive type has a corresponding boxed primitive type (e.g., Integer, Double, Boolean).
Primitives only have values, while boxed primitives have both values and identities.
Boxed primitives have an additional nonfunctional value: null.
Primitives are more time- and space-efficient compared to boxed primitives.
Comparing boxed primitives with the == operator performs an identity comparison, not a value comparison.
Auto-unboxing a null boxed primitive results in a NullPointerException.
Auto-boxing and auto-unboxing operations can lead to unnecessary object creations and performance issues.
Use primitives whenever possible, especially when comparing values or performing computations.
Boxed primitives are necessary in specific situations:
- When using collections, as primitives cannot be directly added to collections;
- As type parameters in parameterized types and methods;
- When making reflective method invocations.

Item 62: Avoid strings where other types are more appropriate

Strings should be used to represent text and should not be used as substitutes for other value types.
Avoid using strings to represent numeric data. Translate numeric data into the appropriate numeric type, such as int, float, or BigInteger, to ensure accuracy and enable numerical operations.
Enum types are better suited for enumerated type constants than strings. Use enums to represent a fixed set of values with distinct identities and behaviors.

Item 63: Beware the performance of string concatenation

The string concatenation operator is convenient for combining a few strings but does not scale well. When using the concatenation operator repeatedly, the time required is quadratic in the number of strings being concatenated because the contents of both strings are copied each time.
To achieve better performance, use a StringBuilder instead of the string concatenation operator when constructing a string from multiple components. StringBuilder provides efficient appending of strings, and its performance is linear in the number of strings being concatenated.
The StringBuilder approach can significantly outperform the string concatenation operator, especially when the number of strings or the size of the resulting string is large. Preallocating a StringBuilder with an appropriate capacity further improves performance by avoiding automatic growth.
Consider alternatives to string concatenation, such as using a character array or processing strings individually instead of combining them if performance is a concern.

Item 64: Refer to objects by their interfaces

Favor using interfaces as types over classes when referring to objects. Parameters, return values, variables, and fields should all be declared using interface types if appropriate interfaces exist.
By using interfaces as types, your code becomes more flexible. If you decide to switch implementations, you can simply change the class name in the constructor (or use a different static factory) without affecting the surrounding code.
It is appropriate to refer to objects by their class rather than an interface when no appropriate interface exists, such as with value classes like String or BigInteger.
Classes implementing an interface but providing additional methods not found in the interface should be referred to by their class only if the program relies on those extra methods.

Item 65: Prefer interfaces to reflection

Reflection provides programmatic access to arbitrary classes and allows manipulation of their constructors, methods, and fields. However, it comes with several drawbacks:
- Loss of compile-time type checking and exception checking;
- Clumsy and verbose code required for reflective access;
- Poor performance compared to normal method invocation.
Reflection is rarely needed in most applications.

Item 66: Use native methods judiciously

The use of native methods has serious disadvantages:
- Native languages are not memory safe, so applications using native methods are susceptible to memory corruption errors;
- Native methods make programs less portable as they are more platform-dependent than Java;
- Debugging native code is more challenging compared to Java code;
- Garbage collection and memory management become more complex since the garbage collector cannot track or automate native memory usage;
- Native methods require writing and maintaining “glue code,” which can be difficult to read and tedious to write.
Use as little native code as possible.
Thoroughly test the native code to avoid bugs that could corrupt the entire application.

Item 67: Optimize judiciously

Premature optimization is often counterproductive. More computing sins are committed in the name of efficiency than for any other reason. Optimization without necessarily achieving it can lead to software that is neither fast nor correct and can be difficult to fix.
Good programs should prioritize sound architectural principles over performance. Write good programs first, and if necessary, optimize them later. Good programs are designed with information hiding, allowing individual components to be changed without affecting the rest of the system.
Performance should be considered during the design process. Avoid design decisions that limit performance, especially in APIs, wire-level protocols, and persistent data formats. API design can have a significant impact on performance, so be mindful of decisions such as mutability, inheritance, and interface usage.
API design and architectural decisions can have real performance consequences. Consider the trade-offs and implications of your design choices. For example, returning mutable objects may result in unnecessary defensive copying, and using implementation types instead of interfaces can limit future performance improvements.
Before optimizing, ensure that your program has a clear, concise, and well-structured implementation. Measure performance before and after each attempted optimization. Profiling tools can help identify performance bottlenecks and guide optimization efforts. Be aware that Java’s performance model is less well-defined compared to lower-level languages, making it essential to measure the effects of optimizations on different implementations and hardware platforms.
Algorithmic changes should be prioritized over low-level optimizations. If a quadratic or inefficient algorithm exists, no amount of tuning will fix the underlying problem.
Performance measurement and optimization are iterative processes. Measure performance, identify bottlenecks, optimize relevant parts, and repeat until satisfied.

Item 68: Adhere to generally accepted naming conventions

Typographical Naming Conventions:
- Package and module names should be hierarchical, separated by periods, and consist of lowercase alphabetic characters and digits. The name should begin with the organization’s Internet domain name, with the components reversed;
- Class and interface names should consist of one or more words, with the first letter of each word capitalized. Abbreviations should be avoided, except for acronyms and common abbreviations.
- Method and field names should follow the same typographical conventions as class and interface names, with the first letter lowercase for methods and fields. Acronyms occurring as the first word should be lowercase;
- Constant field names should consist of uppercase words separated by underscores;
- Local variable names follow similar conventions to member names, with abbreviations and short sequences of characters permitted.
Grammatical Naming Conventions:
- Instantiable classes are generally named with a singular noun or noun phrase. Non-instantiable utility classes are often named with a plural noun;
- Interfaces are named like classes or with an adjective ending in “able” or “ible”;
- Methods that perform actions are named with a verb or verb phrase. Methods returning boolean values usually begin with “is” or “has”;
- Methods returning non-boolean values or attributes of the object are usually named with a noun, noun phrase, or a verb phrase beginning with “get”;
- Field names typically follow the same conventions as class and interface names, using nouns or noun phrases.

Exceptions

Item 69: Use exceptions only for exceptional conditions

Exceptions should be used for exceptional circumstances, situations that are uncommon and unexpected. They should not be used for regular control flow.
Exceptions are not designed to be as fast as explicit tests, so using them for control flow can result in slower code execution.
Placing code inside a try-catch block inhibits certain optimizations that JVM implementations may perform.
The exception-based loop, which relies on throwing and catching exceptions for loop termination, is slower, obfuscates the code’s purpose, and can hide bugs in the code.
Exceptions used for control flow can mask bugs, making debugging more complicated. Bugs that would generate uncaught exceptions in a standard loop idiom may be caught and misinterpreted as normal loop termination in an exception-based loop.
An alternative to a state-testing method is to have the state-dependent method return an empty optional or a distinguished value (such as null) if it cannot perform the desired computation.

Item 70: Use checked exceptions for recoverable conditions and runtime exceptions for programming errors

Checked exceptions should be used for conditions from which the caller can reasonably be expected to recover. By throwing a checked exception, the API designer mandates the caller to handle the exception or propagate it.
Checked exceptions indicate recoverable conditions, and the API user should make an effort to handle them appropriately.
Unchecked throwables, which include runtime exceptions and errors, needn’t and generally shouldn’t be caught. They indicate situations where recovery is impossible, and continued execution would do more harm than good.
Runtime exceptions are typically used to indicate programming errors, such as precondition violations.
It may not always be clear whether a condition is recoverable or a programming error. In such cases, it is a matter of judgment for the API designer. If recovery is likely, use a checked exception; if not, use a runtime exception.
Checked exceptions should provide methods that aid in recovery from the exceptional condition.

Item 71: Avoid unnecessary use of checked exceptions

Overuse of checked exceptions can make APIs difficult to use.
The burden on the programmer increases when dealing with checked exceptions, as they must be handled in catch blocks or propagated outward, placing a burden on the API user.
Another approach is to refactor the method that throws the checked exception into two methods: one that returns a boolean indicating whether the exception would be thrown and another that performs the action. This allows the caller to check the state before invoking the action method.
Use checked exceptions sparingly, consider returning optionals, and throw unchecked exceptions if recovery is not possible or meaningful for the caller.

Item 72: Favor the use of standard exceptions

Reusing standard exceptions in your APIs and programs provides several benefits, including easier learning and usage, improved readability, and reduced memory footprint and class loading time.
The most commonly reused exception types are IllegalArgumentException and IllegalStateException. IllegalArgumentException is used when the caller passes an inappropriate argument value, while IllegalStateException is used when the invocation is illegal due to the state of the receiving object.
It is recommended to use specific standard exceptions like NullPointerException and IndexOutOfBoundsException for certain kinds of illegal arguments and states instead of using IllegalArgumentException.
ConcurrentModificationException is a reusable exception used to indicate concurrent modification of an object that was designed for single-threaded use or with external synchronization.
UnsupportedOperationException is another reusable exception used to indicate that an object does not support a particular operation, typically because it is an optional operation defined by an interface that the object implements.It is advised not to reuse the Exception, RuntimeException, Throwable, or Error classes directly. Treat them as abstract and avoid testing for them directly because they are superclasses of other exceptions.
When reusing exceptions, ensure that the conditions under which you would throw them align with their documented semantics. You can subclass a standard exception to add more detail if needed.
Choosing which exception to reuse can be challenging when multiple exceptions seem applicable. In such cases, follow the rule to throw IllegalStateException if no argument values would have worked, otherwise throw IllegalArgumentException.

Item 73: Throw exceptions appropriate to the abstraction

Higher layers should catch lower-level exceptions and throw exceptions that are meaningful and can be explained in terms of the higher-level abstraction. This is known as exception translation.
Exception translation is achieved by catching the lower-level exception and throwing a higher-level exception that encapsulates the lower-level exception and provides a more meaningful explanation of the problem.
Exception chaining is a special form of exception translation where the lower-level exception is passed to the higher-level exception as the cause. This allows for easy access to the lower-level exception and integration of its stack trace into the higher-level exception’s stack trace.
Exception translation should not be overused. Whenever possible, exceptions from lower layers should be prevented or handled within the higher layer itself.
If exceptions from lower layers cannot be prevented or handled, it may be appropriate for the higher layer to silently work around these exceptions, log them using an appropriate logging facility, and insulate the caller from lower-level problems.
Exception translation allows for better encapsulation, clearer APIs, and the ability to investigate the underlying cause of failures while insulating clients from lower-level exceptions.

Item 74: Document all exceptions thrown by each method

Documenting the exceptions thrown by a method is a critical part of the documentation required to use the method correctly.
Always declare checked exceptions individually and document the specific conditions under which each exception is thrown using the Javadoc @throws tag.
While the language does not require documenting unchecked exceptions, it is wise to document them carefully as they often represent programming errors. Familiarizing programmers with all the possible errors helps them avoid making these mistakes.
Do not use the throws keyword on unchecked exceptions.
It is ideal to document all unchecked exceptions that each method can throw, but in practice, it may not always be achievable due to dependencies on other classes that may throw additional unchecked exceptions.
If an exception is thrown by many methods in a class for the same reason, you can document the exception in the class’s documentation comment instead of documenting it individually for each method.
Failing to document the exceptions that your methods can throw can make it difficult or impossible for others to effectively use your classes and interfaces.

Item 75: Include failure-capture information in detail messages

The detail message of an exception should capture as much information as possible concerning the cause of the failure. It should contain the values of all parameters and fields that contributed to the exception.
Including pertinent data in the detail message aids in diagnosing the cause of the failure. It helps identify specific errors such as incorrect index values, boundary violations, or invariant failures.
It is crucial to avoid including security-sensitive information like passwords or encryption keys in exception detail messages as stack traces may be seen by multiple individuals during the debugging and issue-fixing process.
Do not write lengthy prose descriptions.
The detail message of an exception is primarily intended for programmers or site reliability engineers, not end users. Therefore, information content is more important than readability.
Requiring failure-capture information as parameters in the constructors of exceptions can ensure that the detail message automatically includes the necessary information. This centralizes the code for generating a high-quality detail message in the exception class itself.

Item 76: Strive for failure atomicity

Failure atomicity means that after an object throws an exception, it should still be in a well-defined, usable state, even if the failure occurred in the midst of performing an operation.
Immutable objects naturally achieve failure atomicity because their state is consistent when they are created and cannot be modified thereafter.
For methods that operate on mutable objects, one way to achieve failure atomicity is to check parameters for validity before performing the operation. This ensures that most exceptions are thrown before object modification commences.
Another approach to achieving failure atomicity is to order the computation so that any part that may fail takes place before any part that modifies the object. This ensures that failure occurs before any modification to the object.
A third approach is to perform the operation on a temporary copy of the object and replace the contents of the object with the temporary copy once the operation is complete. This is useful when the computation can be performed more efficiently on a temporary data structure.
Recovery code can be written to intercept a failure and roll back the object’s state to the point before the operation began. This approach is mainly used for durable data structures.
Failure atomicity is not always achievable, especially in cases of concurrent modification without proper synchronization. In such cases, objects may be left in an inconsistent state.
It is not always desirable or practical to achieve failure atomicity, as it can increase cost and complexity. However, it is often easy to achieve once the issue is understood.
API documentation should clearly indicate whether failure atomicity is achieved and what state the object will be left in after a method invocation.

Item 77: Don’t ignore exceptions

When an API declares a method to throw an exception, it is indicating that there may be exceptional conditions that need to be handled.
Ignoring exceptions by surrounding a method invocation with an empty catch block defeats the purpose of exceptions and can lead to disastrous results.
Ignoring exceptions is like ignoring a fire alarm and preventing others from addressing the problem. It is important to handle exceptional conditions appropriately.
There are situations where it may be appropriate to ignore an exception, such as when closing a file input stream where no recovery action is needed and the operation can proceed without issues.
If an exception is intentionally ignored, the catch block should contain a comment explaining the reason for ignoring it, and the variable used to catch the exception should be named ignored to indicate that it is intentionally disregarded.
Ignoring exceptions can lead to a program that continues silently despite errors, potentially causing failures at unexpected points in the code.
Letting exceptions propagate outward can at least result in a swift failure, preserving information for debugging purposes.

Concurrency

Item 78: Synchronize access to shared mutable data

Synchronization ensures that only one thread can execute a synchronized method or block at a time, preventing an object from being seen in an inconsistent state by other threads.
Synchronization not only guarantees mutual exclusion but also ensures that changes made by one thread are visible to other threads. It provides reliable communication between threads.
Reading and writing a variable (other than long or double) is atomic, but it does not guarantee that changes made by one thread will be immediately visible to other threads without synchronization.
Failing to synchronize access to shared mutable data can have dire consequences, even if the data is atomically readable and writable. It can lead to liveness failures and data corruption.
The java.util.concurrent.atomic package provides lock-free, thread-safe primitives, such as AtomicLong, for performing atomic operations on single variables, which can be used as a more efficient alternative to synchronized methods.
The best approach to avoid synchronization issues is to minimize sharing of mutable data. Either use immutable data or confine mutable data to a single thread. If sharing is necessary, ensure proper synchronization or use safe publication techniques.
Safe publication involves ensuring that an object reference is safely shared with other threads by using techniques such as storing it in a static field during class initialization or using volatile or final fields.

Item 79: Avoid excessive synchronization

Excessive synchronization can lead to reduced performance, deadlocks, or nondeterministic behavior.
Excessive synchronization should be avoided for performance reasons. Excessive locking can lead to contention and limit parallelism, as well as hinder the VM’s ability to optimize code execution.
Avoid unnecessary synchronization for mutable classes and document that they are not thread-safe if synchronization is omitted.
If a method modifies a static field and can be called from multiple threads, synchronize access to the field internally to prevent data corruption and ensure deterministic behavior.
Consider advanced synchronization techniques such as lock splitting, lock striping, and nonblocking concurrency control to achieve high concurrency when internal synchronization is necessary.

Item 80: Prefer executors, tasks, and streams to threads

The java.util.concurrent package introduced the Executor Framework, which provides a flexible interface-based task execution facility. It is recommended to use executors instead of writing your own work queues.
Creating an executor service is as simple as calling a static factory method. For example, Executors.newSingleThreadExecutor() creates an executor service with a single background thread.
Tasks can be submitted for execution using the execute() method of the executor service. The executor service takes care of managing the execution of tasks.
To gracefully terminate the executor service, the shutdown() method should be called. This ensures that the executor service will complete any pending tasks before exiting.
The executor service provides various additional functionalities, such as waiting for specific tasks or collections of tasks to complete, scheduling tasks to run at specific times, retrieving task results, and more.
Java provides static factory methods in the Executors class that offer different types of executor services, such as cached thread pools, fixed thread pools, and scheduled thread pools. These cover most use cases, but the ThreadPoolExecutor class allows fine-grained control over thread pool configuration.
Choosing the right executor service depends on the specific requirements of the application. For small programs or lightly loaded servers, Executors.newCachedThreadPool() is often sufficient. For heavily loaded production servers, Executors.newFixedThreadPool() or ThreadPoolExecutor with custom configuration is recommended.
The executor framework separates the unit of work (tasks) from the mechanism of executing it (executor service). This separation provides flexibility in selecting appropriate execution policies and allows easy changes if requirements evolve.
Working directly with threads is discouraged. Instead, think in terms of tasks and let the executor service execute them. This approach allows you to leverage the flexibility and control provided by the executor framework.
For a comprehensive understanding of the Executor Framework, it is recommended to refer to the book Java Concurrency in Practice by Brian Goetz.

Item 81: Prefer concurrency utilities to `wait` and `notify`

The higher-level concurrency utilities fall into three categories: the Executor Framework (covered in Item 80), concurrent collections, and synchronizers.
Concurrent collections are high-performance implementations of standard collection interfaces that internally manage their own synchronization. They provide high concurrency and state-dependent modify operations, making them ideal for concurrent applications.
Synchronizers are objects that enable threads to coordinate their activities. Examples include CountDownLatch, Semaphore, CyclicBarrier, and Phaser.
The concurrent utilities provide high-level abstractions that simplify common concurrency scenarios. For example, a ConcurrentHashMap can be used to implement a thread-safe canonicalizing map, and a BlockingQueue can be used as a work queue for producer-consumer scenarios.

Item 82: Document thread safety

Thread safety, or how a class behaves when its methods are used concurrently, is an important part of its contract with clients.
Failing to document the thread safety aspect of a class can lead to incorrect assumptions about synchronization, resulting in serious errors.
The private lock object should be declared final to prevent accidental un-synchronized access and is particularly useful for classes designed for inheritance.

Item 83: Use lazy initialization judiciously

Lazy initialization can be used to optimize the cost of initializing a class or creating an instance by deferring the initialization of a field until it is accessed.
Lazy initialization should only be used when necessary, as it can increase the cost of accessing the lazily initialized field.
Measure the performance impact of lazy initialization to determine whether it is beneficial for a specific scenario.
In the presence of multiple threads, lazy initialization requires synchronization to avoid bugs.
Normal initialization with the final modifier is usually preferable to lazy initialization for most fields.

Item 84: Don’t depend on the thread scheduler

The thread scheduler determines which threads get to run and for how long when many threads are runnable. However, the thread-scheduling policy can vary between operating systems, so relying on specific details of the policy can lead to non-portable programs.
To write a robust, responsive, and portable program, aim to keep the average number of runnable threads close to the number of processors. This minimizes variations in behavior caused by different thread-scheduling policies.
To keep the number of runnable threads low, ensure that each thread does some useful work and then waits for more. Thread pools should be sized appropriately, and tasks should be neither too short nor too long to avoid dispatch overhead.
Avoid busy-waiting, where threads repeatedly check a shared object waiting for its state to change. Busy-waiting puts unnecessary load on the processor and reduces the amount of useful work that can be accomplished. It also makes the program vulnerable to the thread scheduler’s behavior.

Serialization

Item 85: Prefer alternatives to Java serialization

Serialization in Java has proven to be risky, with problems related to correctness, performance, security, and maintenance.
The attack surface of serialization is significant and constantly growing. Deserializing objects can execute code from any type on the classpath, making it vulnerable to exploits.
Security researchers have discovered and exploited vulnerabilities in deserialization, leading to serious attacks, such as the SFMTA Muni ransomware attack.
Deserialization bombs can be used to mount denial-of-service attacks by causing deserialization of byte streams that take a long time to process.
The best defense against serialization exploits is to avoid deserializing untrusted data altogether. Serialization should be replaced with alternative mechanisms for translating objects to byte sequences.
Cross-platform structured-data representations like JSON and Protocol Buffers offer advantages such as portability, high performance, tooling support, and a large community.

Item 86: Implement `Serializable` with great caution

Implementing Serializable has long-term costs, as the serialized form of a class becomes part of its exported API. Changing the class’s internal representation while maintaining compatibility with the serialized form can be challenging and may limit the class’s evolution.
Serialization introduces the risk of bugs and security vulnerabilities. Deserialization acts as a “hidden constructor” and must guarantee invariants established by constructors, while also preventing unauthorized access to object internals.

Item 87: Consider using a custom serialized form

When the default serialized form is inappropriate for a class, it can result in several disadvantages, such as permanently tying the API to the current internal representation, consuming excessive space and time during serialization, and potentially causing stack overflows.
Regardless of the serialized form chosen, any synchronization imposed on the object’s methods should also apply to the writeObject method to prevent resource-ordering deadlocks.
Taking the time to design a custom serialized form that accurately represents the logical data and excludes unnecessary implementation details can lead to more flexible, efficient, and maintainable serialization. The default serialized form should only be accepted if it aligns well with the class’s logical state.

Item 88: Write `readObject` methods defensively

The readObject method is similar to a public constructor for deserializing objects, and it requires the same care as any other constructor to ensure the object’s validity and invariants.
To prevent invalid objects from being deserialized, the readObject method should perform validity checks after calling defaultReadObject.

Item 89: For instance control, prefer enum types to `readResolve`

When a class is serialized and deserialized, the readResolve method can be used to substitute another instance for the one created during deserialization.
The readResolve method can be implemented in a singleton class to return the original singleton instance and maintain the singleton property during deserialization.
The preferred approach for instance control is to use an enum type. Enum types guarantee that only the declared constants are the instances of the class, preventing any additional instances from being created during deserialization.

Item 90: Consider serialization proxies instead of serialized instances

The serialization proxy pattern involves designing a private static nested class, called the serialization proxy, that represents the logical state of the enclosing class in a concise manner.
The serialization proxy should have a single constructor that takes the enclosing class as a parameter and copies its data without performing any consistency checking or defensive copying.
Both the enclosing class and its serialization proxy should implement the Serializable interface.
The serialization proxy pattern eliminates the need for explicit field-level validation during deserialization and ensures that the invariants of the enclosing class are maintained.

Conclusion

While I did not find this book to be particularly entertaining, it is a very useful reference for Java developers. It covers a wide range of topics and provides a lot of useful information. I would recommend this book to anyone who is interested in learning more about the Java language and its best practices.

Resources and references

Effective Java, Third Edition - Joshua Bloch.
Java Concurrency in Practice - Brian Goetz.

Book summary: The Effective Engineer

Sébastien Lavoie — Sun, 16 Apr 2023 14:49:00 -0600

Introduction

This wonderful, mostly non-technical book is a compilation of the best practices and lessons learned by the author, Edmond Lau, during his impressive career as a software engineer. It is a must-read for anyone who wants to improve their skills and become more effective at what they do. The following are short excerpts from the condensed knowledge found in the book, sprinkled with some minor comments of my own along the way. These are extracted from the book’s takeaway sections and headings: I wholeheartedly recommend reading the work in its entirety for an immersive exposure to the fantastic storytelling capabilities of Edmond!

Book summary

Part 1: Adopt the Right Mindset

Focus on high-leverage activities

Leverage = Impact produced / Time invested

Leverage is the ROI for the effort put in.
Meta-skills are important to know where to focus one’s time and energy to translate more of one’s efforts into impact.
Leverage your time by always finding ways to perform activities quicker and making sure those activities will have a meaningful impact.

Optimize for learning

Make your learning rate a priority: it compounds like interest over time.
Study code for core abstractions written by the best engineers at your company.
Write more code.
Go through any technical, educational material available internally.
Master the programming languages that you use.
Send your code reviews to the harshest critics.
Enroll in classes on areas where you want to improve.
Participate in design discussions of projects you’re interested in.
Work on a diversity of projects.
Make sure you’re on a team with at least a few senior engineers whom you can learn from.
Jump fearlessly into code you don’t know.
Learn new programming languages and frameworks.
Invest in skills that are in high demand.
Read books.
Join a discussion group.
Attend talks, conferences, and meetups.
Build and maintain a strong network of relationships.
Follow bloggers who teach.
Write to teach.
Tinker on side projects.
Pursue what you love.

Prioritize regularly

Track to-dos in a single list.
Focus on what produces value directly.
Focus on the important and non-urgent.
Limit the amount of work in progress.
Use implementation intentions (if-then planning).
Prioritize routinely.
Write down and review to-dos.
Reduce context switches.

Part 2: Execute, Execute, Execute

Invest in iteration speed

Move fast to learn fast.
Invest in time-saving tools.
Shorten your debugging and validation loops.
Master your programming environment.
Get proficient with your favorite text editor or IDE.
Learn at least one productive, high-level programming language (scripting).
Get familiar with UNIX (or Windows) shell commands.
Prefer the keyboard over the mouse.
Automate your manual workflows.
Test out ideas on an interactive interpreter.
Make it fast and easy to run just the unit tests associated with your current changes.
Don’t ignore non-engineering bottlenecks.

Measure what you want to improve

Use metrics to drive progress.
Pick the right metric to incentivize the behavior you want.
Instrument everything to understand what is going on.
Internalize useful numbers (e.g., number of active users, requests per second, amount of data accessed and written daily, etc.).
Be skeptical about data integrity.
Log data liberally, in case it turns out to be useful later on.
Build tools to iterate on data accuracy sooner.
Write end-to-end integration tests to validate your entire analytics pipeline.
Examine collected data sooner.
Cross-validate data accuracy by computing the same metric in multiple ways.
When a number does look off, dig into it early.

Validate your ideas early and often

Find low-effort ways to validate your work.
- Approach a problem iteratively to reduce wasted effort.
Continuously validate product changes with A/B testing.
- Reduce the risk of large implementations by using small validations.
Beware the one-person team (you need feedback early to make sure you’re working on the right thing!).
Be open and receptive to feedback.
Commit code early and often.
Request code reviews from thorough critics.
Ask to bounce ideas off your teammates.
Design the interface or API of a new system first.
Send out a design document before devoting your energy to your code.
If possible, structure ongoing projects so that there is some shared context with your teammates.
Solicit buy-in for controversial features before investing too much time.
Build feedback loops for your decisions.

Improve your project estimation skills

Project estimation is one of the hardest skills that an effective engineer needs to learn. But it’s crucial to master.
To produce accurate estimates:
- Decompose the project into granular tasks.
- Estimate based on how long tasks will take, not on how long you or someone else wants them to take.
- Think of estimates as probability distributions, not best-case scenarios.
- Let the person doing the actual task make the estimate.
- Beware of anchoring bias (e.g., hearing about a low estimate from someone else may skew our own estimate later to be too low).
- Use multiple approaches to estimate the same task (e.g., estimate from past experiences, decompose a larger task into smaller ones and estimate each one).
- Beware the mythical man-month. Having more people on a project doesn’t necessarily mean it will be completed faster. Communication overhead, context switching, and other factors can slow down the team as much as $O(n^2)$ considering the number of people involved.
- Validate estimates against historical data.
- Use time-boxing to constrain tasks that can grow in scope.
- Allow others to challenge estimates.
Allow buffer room for the unknown in the schedule.
Define measurable milestones.
Do the riskiest tasks first.
Know the limits of overtime.

Part 3: Build Long-Term Value

Balance Quality with Pragmatism

Establish a culture of reviewing code.
- Catch bugs or design shortcomings early.
- Increase accountability for code changes.
- Provide an avenue for sharing best practices.
- Increase long-term agility.
Invest in good software abstractions to simplify difficult problems.
- Reduce the complexity of the original problem into easier-to-understand primitives.
- Reduce future application maintenance and make it easier to apply future improvements.
- DRY principle: solve the hard problems once and re-use the solutions multiple times.
Scale code quality with automated testing.
- Make large refactors with confidence.
- Offer executable documentation.
- Don’t test everything: focus on the most important parts of the code and make sure everything critical is covered.
Manage your technical debt.
- Pay it periodically. Incur it when necessary to meet deadlines.
- Repay the debts with the highest interest rates first (i.e., focus on what produces the most leverage).

Minimize Operational Burden

Embrace operational simplicity.
- Increased complexity introduces more potential single points of failure.
- New engineers face a steeper learning curve when learning and understanding the new systems.
- Effort towards improving abstractions, libraries, and tools gets diluted across the different systems.
- Do the simple thing first.
Build systems to fail fast.
- Pinpoint the source of errors.
- Make debugging easier by not masking your errors and by not deferring failures until later.
Relentlessly automate.
- Don’t underestimate the future frequency of the task.
- Internalize the time savings over a long time horizon.
- Automate mechanics over decision-making.
Make batch processes idempotent.
- At least, make processes “retryable” if they cannot be made idempotent.
Hone your ability to respond and recover quickly.
- Plan and practice failure modes.

Invest in Your Team’s Growth

Make hiring everyone’s responsibility.
- Identify which qualities you care about the most in your colleagues: keep the bar high.
- Make sure the recruiting process is effective.
- Adapt interview problems to different levels of difficulty based on the candidate’s experience.
Design a good onboarding process.
- Ramp up new engineers as quickly as possible (e.g., with codelabs).
  - Help the people around you be successful.
- Impart the team’s culture and values (e.g., have onboarding talks).
- Expose new engineers to the breadth of fundamentals needed to succeed (e.g., with mentorship).
- Socially integrate new engineers onto the team (e.g., give them starter tasks to feel they’re part of the team faster).
Share ownership of code (increase the bus factor).
- Avoid one-person teams.
- Review each other’s code and software designs.
- Make sure the team is exposed to different types of tasks and responsibilities regularly.
- Focus on readable and high-quality code.
- Share software decisions and architecture clearly.
- Make sure code and workflows are documented properly.
- Invest in teaching and mentoring.
  - The more effective the team becomes, the more freedom there is to work on new projects.
Build collective wisdom with post-mortems (e.g., at NASA, these become the user manual).
Build a great engineering culture.
- Optimize for iteration speed.
- Always automate.
- Use the right software abstractions.
- Nurture a respectful working environment.
- Allot experimentation time.
- Foster a culture of learning (CI/CD: continuous improvement, continuous delightfulness).
- Hire the best!

Conclusion

Edmond opened my eyes to the importance of being an effective engineer, showing what that entails and how to concretely achieve it. His extraordinary technical journey and knowledge of the field are evident throughout the book, and I found myself nodding in agreement with many of his points. He made me think about how I could apply his advice to my own work. Notably, the key concept of leverage resonated deeply with me and ended up being the cornerstone of the final project I built for my bachelor’s degree: ProductiviDo - An efficient task planner focusing on high-leverage activities.

Resources and references

Edmond Lau - The author’s personal website.
ProductiviDo - A simple and efficient todo-app built with React-Native.
The Effective Engineer: How to Leverage Your Efforts In Software Engineering to Make a Disproportionate and Meaningful Impact - goodreads.com.
The Effective Engineer - by Edmond Lau.

Book summary: Letters to a New Developer

Sébastien Lavoie — Mon, 08 Nov 2021 10:12:00 -0600

Introduction

I’ve taken quite a few notes while devouring that book, which is a quick and easy read. It’s not the typical non-fiction, technically-oriented manual: this book makes you feel like having an older family member taking the time to sit right next to you to openly share all sorts of golden nuggets from a lifetime of rich and varied experiences so you can get prepared to face the challenges that lie ahead in your own career and avoid some of the more common mistakes during the journey. It is the kind of publication you can read literally five minutes at a time thanks to the convenient format it adopts.

Some of the following notes are verbatim and reading the whole title will be worth it! Nevertheless, you will find below some passages that deeply resonated with me, reflecting the gist of this prose from my perspective. Beware! There are numerous gems to be gleaned from this excellent author.

Book summary

First month at a job

See problems as opportunities to contribute.
During the onboarding, figure out:
- All the HR stuff: benefits, agreements, bonuses, interacting with different departments, meetings, requesting vacation, raises/reviews cycles.
- And the technical stuff too: who to ask questions to, how to ask them (batch them, chat, meeting, etc.), how long to work on a problem before asking for help, how to communicate progress, how to set up a local development environment, CI/CD and branches process, when do you know you’re done working on a task, how are tasks managed (manager, issue tracker, etc.).
Questions that arise and have no answers → See where to document them (e.g. wiki).
First impressions:
- Be there early.
- Say what you’ll do, then do it.
- Research before asking questions (and record answers).
- Volunteer to take extra work (don’t become a punching bag, though).
- Own your mistakes but don’t make the same ones twice.
- Be polite and professional, always.
- Make sure with manager we’re on the same page, working on the right stuff, at the right cadence with appropriate updates.
- Write docs to make the next hire easier.
- Have the reputation to be a hard, smart worker: it will follow you.
Be ready for the trepidations: celebrate successes ("today I [fixed, learnt…]").
To excel:
- Communicate what you’re working on.
- Ask questions.
- Don’t make the same mistake twice: write down what went wrong and plan to avoid repeating them.
- Show up consistently.
Know the team: their names, their roles, their behaviours (who posts what, who is in which meetings, who seems funny and approachable on Slack, etc.).
Read code and take notes: dig into a section of the system, follow data flow, make diagrams of how things are connected.

Questions

Ask prepared questions:
- Research before asking.
- Find where to search (Slack, issue trackers, YT, internal docs or wiki, etc.).
- But also be mindful of how long you should spend time searching (Is there a tight deadline? Are you wasting your time?).
Ask good questions:
- Specify the problem in detail, narrow the scope as much as possible.
- Show you’ve done research. Links, videos, posts, logs (without sensitive info), etc.
- Follow up after a day or so to share additional research.
- Express gratitude.
- If you have the answer, add it.
Don’t be afraid to ask questions:
- If it’s a learning experience, spend more time figuring out the answer.
- The more time you have before the task is due, the more time you should spend looking for an answer.
- How busy is the rest of the team? If they can’t help, you’ll have to do it yourself.
- If there’s a bug that’s really specific to the internal project, asking for help from coworkers is probably best (be careful not to disclose business knowledge!).
- Have you tried working on other aspects of the task? It may unblock you.
- Put in the effort before asking: research, list hypotheses, etc.
Ask why:
- It may help prevent mistakes down the line (e.g. wrong choice of tech) and get more perspective, understand better.
- Document findings in wiki or similar (could be in a question/answer format).
If you don’t know something, don’t guess or make an incorrect decision: admit it and say you’ll find out the answer (may have to ask others in the process too).

Writing

Read your texts out aloud: spot typos, awkward sentences, etc.
Document the intent behind what you’re doing (code, reason for change, who asked what…).
Emails:
- As short as possible. Otherwise, add executive summary at the top.
- Is it sensitive? Maybe have face-to-face instead.
- Add links to supporting documents rather than attaching them. Email chains are hard to follow: may put them in a document instead.
- Don’t use relative time references.
- Keep them focused: go into one topic. New topic = new email with different subject line.
Real-time messaging: Default to public channels to benefit the organization.
Write a technical ebook: working on a complex project over time and being able to see the high-level and details, all presented in a coherent way for the readers.
Write and update technical documentation: you save time in the long run, it’s useful for you and the rest of the organization.
Blog: this is the process of clarifying your own thoughts. You’ll be a better writer and thinker for it.
Motivation about writing:
- It crystallizes thoughts, make them clearer;
- Builds credibility;
- Helps others;
- Illustrates an ability to convey technical information and context.

Tools to learn

Leverage for increased productivity:
- Test suite: living documentation. Can evolve code base without fear.
- Libraries and frameworks: saves time.
- IaaS (infrastructure as a service, e.g. AWS EC2): can use APIs to manage.
- Paas (platform as a service, e.g. Heroku): Allows to focus on business logic.
- Saas (software as a service, e.g. Google Apps): integrate with existing software.
Command-line:
- Typing is quicker than using GUIs for many tasks.
- Can automate recurring tasks easily.
- Can easily share task scripts with others.
- jq, awk, sed: put them to good use.
Version control: if in doubt, use it, except for large files and other scenarios that don’t make sense.
Text editor: learn one well.
IDEs: Use them when it makes sense (programming in Java with a text editor? Probably a bad idea).
Standard library: get a good overview of what’s available, leads to transferable skills, more idiomatic code, better tested, etc.
Automated testing:
- Prevents bug regression.
- Serves as live documentation.
Network engineering: Learn about it, it will pay off. Know:
- Basics of routing;
- Basics of DNS;
- Rundown of the OSI model;
- TCP/IP, HTTP, what a proxy is;
- Answer questions like How do CDNs work, what’s the difference between HTTP and WebSockets, how does SSL work, what can nginx be used for…
SQL: this is fundamental knowledge as it’s almost everywhere.
Debuggers: learn how to debug in your IDE, on the command-line and in a web browser (your IDE won’t always be available).
Benchmarking: do not optimize prematurely and use benchmarking tools when performance matters to see if the code is fast enough.
Search engines: learn to be an expert Googler.

Practices

Solve problems, don’t just write code:
- Use library/framework.
- Use third-party SaaS tool.
- Make sure tasks need to be done. (Why are you doing it? Does it provide value?)
- If a task isn’t recurring often enough, manual work may be the best way to go (time to automate vs. actual savings).
Think ahead, envision all paths (not just the happy one) before taking a decision.
Read code: scan it; dive down; use the scientific method to make changes and debug.
Get good at estimating your work:
- Opportunity cost (can’t do everything: prioritize and do the tasks that bring the most value).
- Scheduling: software is not built in a vacuum, hard and soft deadlines will occur.
- Discussing requirements first can save a lot of troubles and money: building the wrong thing quickly is of no use. Use lightweight prototyping tools instead of building the whole software.
- Recommended reading: Software Estimation: Demystifying the Black Art, by Steve McConnell.

Here’s one way to keep track of your estimates in a spreadsheet:

Task	Low estimate	High estimate	Notes, questions, research	Final estimate	Estimate in days
Requirements definition, research, development, testing, deployment, estimates on bug fixes…	Everything going smoothly.	Facing obstacles, having to rebuild part of the system, etc.	Answer questions and verify assumptions to complete the estimate.	(low + high) * 1.2 (add 20%, “fudge factor”)	Total hours estimated divided by number of ideal hours per day

Tracking the actual accuracy of tasks can be insightful too.
Always tell people who are depending on the completion of a task if it’s going to take longer than expected. Share alternative solutions if you have any.
Even for side projects or when working on open source projects, it may be useful to practice estimating (and users like seeing a roadmap).
Debug systems:
- Make the problem as simple as possible.
- Begin with an hypothesis and either prove it or refine it.
- Determine the desired end state: fix the root problem but if it’s too costly, find a workaround if possible.
- Pay attention if anything seems amiss.
- Keep notes about what you’ve tried.
- If there’s a new bug, inspect recent changes in the log.
- Write an automated test before fixing the bug so it doesn’t reappear and you’ll be sure when the bug was fixed.
- Follow the flow of data (e.g. in a three-tier application, start with the browser or with the database).
- Minimize impact for users if the bug is in the production environment. Ideally, test on the staging environment.
- Test the right thing. Make sure that what’s being tested mirrors as closely as possible where the bug appears.
Assume positive intent: be solution-focused.
- ROI on trust: about 4% of the population are sociopaths; meaning 96% of the population has some working conscience and could be trusted by default to reap great benefits. This may speed decision making, for instance.
Express gratitude: it will make you feel better and showing appreciation to others will make working with colleagues a breeze. Thanking people and writing a gratitude journal will be helpful.
Cultivate the skill of undivided attention:
- To produce your best output, you need to commit to deep work.
- To thrive in today’s economy, you need to be able to quickly master hard things and be able to produce at an elite level in terms of both quality and speed.
- To learn hard things quickly, you must focus intensely without distraction.
- Add routines and rituals to your working life to limit the amount of willpower required to get started.
- Book recommendation: Deep Work: Rules for Focused Success in a Distracted World, by Cal Newport.
Build empathy: Remember your own frustrations. Your users are people who can struggle on tasks you’d find simple yourself. They’re trying to make something work, just like you.
Don’t complain about the code:
- It’s not helpful.
- It displays a lack of empathy.
Avoid jargon: If you can’t explain it to a non-technical user, you don’t understand it well enough (good framework: try the Feynman Technique). You gain clarity for yourself, the ability to teach others and you can influence your organization. (Personal additional: get good at critical thinking and use frameworks for better thinking).
Time is money: buying services from others gives you time.
- Buying a book or video instead of reading free documentation.
- Buying and using exceptional tools (e.g. JetBrains IDEs).
- Paying for support.
- Buy commercial software.
- Pay for consulting or training.
Say no:
- If there are pending tasks, ensure they are worked in the right order of priority.
- Life is short: if you end up working 90 hours per week, make sure you’re happy doing it and are not sacrificing other important aspects.
Build on your own: pick a project you can envision yourself sticking to for more than six month and learn.
Consistency is key: learn by showing up every day. Becoming great at something takes time.

Understanding the business

Software is about people, not code:
- Software is created for people.
- Users need to be heard to buy in.
- Most people don’t care about the code. Their goal is to get things done. Beautiful code that doesn’t solve the right problem is useless.
Outcomes over output: the end-goal for the business is more revenue, more profit, more users, more product availability, happier users, etc. Your contributions should be holistic in nature and work towards achieving these goals.
Understanding the big picture of why money is spent on certain projects or services pays off as you can better contribute to the bottom line of the company by knowing why things are done the way they are.
Business model: know how money is being made. Get a good understanding of the domain in which the business operates.
Knowing how software is used at the company helps you to understand the business.
The size of a company impacts how it solves problems: a bigger company will usually move more slowly towards its goals when change is required, attacking possibly bigger problems with powerful tools and teams. A smaller company may pivot more quickly and shift focus, but it may not work on problems of comparative scales.
Starting a company:
- As a new developer, starting one wouldn’t be wise. Learning to become a software developer and learning how to run a business all at once can lead to a huge amount of stress.
- It will take longer than you think.
- Know your financial runway (“burn rate” vs. what you have in the bank). Extend it by lowering the burn rate.
- Consider your emotional runway: how are things going for you outside of work? Are there any trying events like moving or having a new baby?
- Talk to your customers: learn from them. Get feedback.
- Provide value to customers: you won’t have time to make everything go as smoothly as you’d like, but the customer must still be served.
- Know your market.
- Be ready to move away from code and focus more on a position of management as the company grows.
Learn from your customers:
- Digging into a ticketing system will be informative to understand how a product is being used and may reveal flaws or bugs.
- Focus on the problems mentioned, not on the solutions proposed.
- Ask them about their pressing problems, not only those that have been reported so far. This may inform about issues with related systems.

Learning

Never stop learning:
- Be clear about why you want to be learning.
- Once you have the why, determine the what that will take you there.
- Once you have both of the above, find the how.
- Execute.
Build expert intuition:
- It’s the difference between a junior and a senior developer.
- A regular world + many opportunities to learn + frequent feedback + expert intuition.
- Regular world: gives a chance to find out whether you’d prefer to specialize in a specific branch of the software development tree or remain a generalist.
- Many opportunities to learn: write code, work on technical projects and observe those who are more senior than you.
- Frequent feedback: code reviews and one on ones with the manager. Reflect on your performance with a daily journal.
Know what to learn (i.e. general skills vs. specific technology and techniques):
- Domain knowledge: understand the business you are in, who the major players are, etc. If you stick in a given domain long enough, you become more valuable as this kind of knowledge tends to last a long time. Talk to experts and read books.
- Theoretical expertise: data structures and algorithms, HTTP and best practices fall within this category. It serves for years as a solid foundation for everything else. Books are a fine source to delve deeper.
- Practical knowledge:
  - React, Kubernetes, Rails are some examples of specific technologies that belong in this category.
  - Have a good understanding of the underlying technology whenever possible (e.g. learn the language in depth, not just the framework).
  - This type of knowledge tends to age quickly and can be learnt through videos, conference talks and tutorials.
- Leadership knowledge: This will pay dividends through your career. Books and experience in the real-world are useful here.
Avoid being an expert beginner (an authority with nontransferable skills):
- Never believe you have all the answers.
- Don’t bend tools to do something they weren’t meant to do.
- Don’t ignore best practices (but don’t blindly apply them everywhere either!).
- Keep in touch with the larger software community: you may temporarily be at the top somewhere technically speaking, but that won’t remain true in a bigger context.
- Pair with people that are more experienced than you: ask them questions, read the pull requests they submit.
Pattern match to be a just-in-time learner: explore by pattern and analogy (e.g. compare terminology that’s similar to tools you’ve used before) and learn just enough to get the task done. Learn the nuances as you go.
Learning boring stuff:
- Focus on the big picture. Why are you learning this?
- Notice the fun parts.
- Take breaks when needed. If no strict deadline is in sight, you might cross off a different task on your to-do list for now.
- Automate what you can but consider clearly the time savings when doing so.
- Learn relevant things: this applies once you have a base to lean on, but accumulating random concepts that aren’t often applicable after that isn’t useful (unused knowledge rots and gets forgotten).
Your team will teach you:
- They can teach you more than you can learn on your own: tools; languages; frameworks; business domain knowledge; approaches to problem-solving; understanding of the problem; stakeholder empathy.
- Observe how senior people work (face-to-face, read their code and pull requests).
Use an RSS reader: for blogs, online community discussions, tags in Stack Overflow, news sites.
Listen to podcasts: good to gather ideas about high-level concepts while doing other things (dishes, exercise, watering plants, cooking, etc.).
- Listen to those that are domain specific to help you at work.
- Technology specific: expose yourself to tools, techniques and libraries.
- General software development: those are broadly applicable to software engineering and will work across different jobs you have within the industry.
Subscribe to email newsletters: great to get curated content on a given topic. These could include software development practices, security, AWS and career skills.
- Find them with searches like <subject area> weekly/email newsletter.
- Read the archives first to get a sense of whether you’ll enjoy the content.
- Like with podcasts, focus on what’s interesting and skim the rest.
- When sources lead to more articles of interest, those can be captured in your RSS reader.
- Good to explore new technologies and frameworks.
- To start your own, TinyLetter is a great option.
Read great books about software development: don’t look for cutting-edge information but rather for a source of timeless practices.
- Good examples include The Mythical Man-Month, The Pragmatic Programmer, Refactoring.
- Ask great engineers you respect for recommendations.
Listen actively:
- Do not multitask.
- Take notes of… salient points; ah-ha moments; terms to review in the future (those concepts you may not understand). Note the date of the conversation as well.
- If it is a video chat, see whether it can be recorded. Turn on video if possible to get contextual clues.
Learn two programming languages:
- Lets you see the strengths and weaknesses of your first language.
- May support concepts that weren’t there before (e.g. classes in Java vs. their absence in Perl).
- Makes it easier to learn a third language.
- Illustrates different approaches to common problems.
- Teaches you how languages fit certain problems better than others.
- Makes you less passionate about your first language. Programming languages are only tools.
- Makes it clear what you understand about language #1.
- Tutorials are great to get started and side projects even better to cement the learning.
- Generally, learn at least two of “everything” (e.g. databases, frameworks, development methodologies, etc.).

Mistakes

Get used to failure: learning something new is difficult. Document internal knowledge as best as you can so the same mistakes do not repeat themselves. Look around (online, colleagues…) to make sure the problem you are trying to solve hasn’t been worked on already and take any new information into account.
Making mistakes is okay:
1. Find out what the oversight was so you don’t repeat the same mistake.
2. Acknowledge you made an error.
3. Clean up the mess, with or without help.
4. Avoid making the same mistake again. You might keep notes around, write a blog post, etc. Document it or create a script to solve the issue from now on if applicable and share your new knowledge with the rest of the team.
Mistakes are forgiven, hiding them is not:
- Make sure you did a mistake to start with.
- The people who need to know about your errors should be told. Transparency and honesty are important.
- Think of a plan to fix the mistake (both short-term and long-term).
Don’t make the same mistake twice:
- Make sure you understand what the mistake was.
- Dive deeper when it makes sense. For instance, it is worth mastering a version control system as this is a tool that’s going to be used all the time and is critical to understand when working with other software engineers.
Don’t be afraid to “fail”: the only true failure is to quit working towards success.
- Failures don’t stop happening when you become a “better” developer.
- The more you fail, the more you learn.
You don’t know what you don’t know. Doing pattern matching and recognizing concepts at a high level will help when there’s a need to dig deeper.
When you see someone else making a mistake:
- Make sure you have all the necessary context (you usually don’t have it) before jumping in to shine a light on how you think things could be done or fixed.
- Make sure you fully understand the issue at hand.
- Think about the ramifications of a poor decision: the higher the stakes are, the more likely it is that you should/could intervene.
- Contemplate your role: depending on the relationship you have with that person, tolerance levels will change (personal note: ask questions early as needed, but make sure you show progress as stagnation won’t lead to joyful relationships with your colleagues and may get you fired).
It’s OK to fail and it’s OK to feel bummed about it. See how core/important the task is for the company, whether somebody else would be better positioned to do it, how long it would take you to become good at it, whether you enjoy it, whether there’s another way to solve the problem, if there’s someone else at the company who could teach you. Don’t beat yourself up with despair: be strategic about the way you spend you efforts.
Admit your weaknesses… and own them.
- Is it something innate, like bluntness, or is it something you can learn, like Python?
- If a weakness is related to a core competency needed for your job, be proactive in overcoming the obstacle or find another job that’s better suited to your skills.

Your career

Favor learning over earning: take the job with the highest learning potential.
- Beware of stunting your growth by working alone.
- You will become more valuable to your future employers and have a better idea of what you like.
You will never be in a better position to leave a bad job than before you start: interviewing is a two-way street.
- Do your research before accepting a job offer.
- Investigate through your network, e.g. LinkedIn, if you have a connection that worked at that company and ask about the good and bad of this organization.
- Ask good questions about the company during the interview.
- As an exception, you might want to consider getting your feet wet in the industry with your first job by being less picky, especially if the job market is bad. Experience will prove useful.
Pick a flaw: no company is perfect.
- You don’t want an indifferent team just punching the clock and waiting for the week to be done.
- Avoid nonsense: ask how a typical day goes, who makes decisions about priorities, in what kinds of projects does the company shine and what the best and worst parts of a job are.
Preparing for a recruiting event. Have: a resume; a good intro to yourself; a good conversation you can have; be well presented.
- Resume: make sure you have the address, phone, email, GPA and graduation date (for students) at the top. It should show you’re motivated, skilled, passionate, adaptable, collaborative and articulate. When you have less experience, projects should be the centerpiece of your resume. Project descriptions should be brief and focus on the what, why and the outcome, avoiding mentions of tech stack unless it adds to the narrative. These can be side hustles, open source, personal interest or hackathons. Have more than one resume for different audiences.
Practice programming: you learn by doing.
Start at a consulting company if you’re looking to gain experience across technologies, domains and businesses. Work for a small one if you want to have an impact. This will provide contacts and set you up for future work. Seek out mentorship, request conference attendance and pursue assistance as formal education programs tend to be lacking in those environments.
Potential vs. delivery: Ask smart questions, show you’ve learned stuff. Say what you’re going to do, then do it.
- The more experienced you become, the more you are assessed on your ability to deliver.
- Expect to demonstrate your experience during interviews.
- Periodically, or when you complete a project, take a few minutes to write some lessons you’ve learned.
- Take risks early as pivoting later on in your career becomes more difficult.
- Book recommendation for more senior developers when switching domains, tech stacks or employers: What Color Is Your Parachute, by Richard N. Bolles, with Katherine Brooks.
Maintain work-life balance: preserve a firm boundary. Work is a marathon, not a sprint.
- Get clear on how the employer expects you to handle unplanned work with conflicting priorities.
Listen to the voices when they help and ignore them when they don’t:
- Be willing to do things you didn’t think you wanted to do.
- Connect with non-tech people outside of work to take a break and experience life from their point of view too.
Manage your career: know your goals; communicate your goals; progress towards them.
- Knowledge: pick an interest and follow it. Plan for a decade or more, with some milestones in between.
- Communication: communicate your desires and ambitions. Good companies want to see their employees grow.
- Progress: study for a certification, read a book, go to a meetup. Be active.
Know your runway: this is the time you have at your current spending until you have no money. Calculate it once a month and know how long it would take to get a new job (guess).
- Get a job before you need to to avoid accepting an ill-fitting job due to desperation.
- Cutting expenses is hard but it’s where you usually have the most control.
- Spending savings for a career transition is an investment in yourself.
- Activities that draw down your savings should lead to new opportunities and valuable personal knowledge.
Managing one on ones: for remote ones, it’s best to have a great Internet connection, a quiet space and video turned on (personal note: you do lose visual clues without video, but you can connect deeply without anyone being too self-aware with voice-only communication).
- Regular ones (weekly or bi-weekly) are preferred so you don’t dread feedback only when you ask for a raise or do something wrong. Knowing your manager beyond these scenarios will help.
- Reasons to schedule them: understand where we are headed so I know what to learn; know how I can best help the manager and the company; understand your priorities better.
- The direction of the one on one should be determined by the employee.
- Shoot for regular ones that do not get re-scheduled. Otherwise, propose having them less frequently if needed.
- If one-on-one meetings aren’t desirable, go for an asynchronous weekly status report and get feedback from your manager this way: it is critical for your career growth early on in your career.
- Come with a prepared agenda to make the most of them. A shared document in reverse chronological order works well. Example questions to add:
  - How should I have handled situation X?
  - I would like to learn more about Y; what are the opportunities?
  - I’m struggling with <problem>, do you have any suggestions?
  - What are the challenges you see facing our team during project Z?
- You should be able to trust and rely on your manager/boss. If not, improve the relationship or go elsewhere: being constantly under threat and not knowing what to expect is mentally draining.
Write a brag document: show everything you’re proud of so they know you’re a great team member. It should be thorough yet easy to read. Along with the agendas from your one-on-one meetings, it will serve to highlight your accomplishments for your next performance review.
Be adaptable and authentic.
Working remotely: you need a fast Internet connection; iron discipline; be okay with solitude and have the ability to work through communication obstacles.
- If you are comfortable asking a dumb question, remote work can work well for you.
- You will need to get used to asking questions and interrupting others as you more often than not won’t have enough context to infer whether it’s a good time to ask or not. It’s better than the alternative of wasting your time.
How to go through a layoff: this isn’t personal and you will get through it.
- Ask questions:
  - Know the deadline to sign the necessary documents;
  - Find out if there’s a severance and how much is it;
  - What about funds like 401k, FSA or HSA;
  - How can I say goodbye to teammates (emails and LinkedIn are good options);
  - What about company’s property, e.g. laptop, books and equipments;
  - Who can I contact if have I more questions;
  - Make sure they have your personal email;
  - Take notes of what happened;
  - Get involved with a lawyer before signing anything (e.g. non-compete agreements).
Use LinkedIn:
- Send a note when you connect and keep in touch with past colleagues.
- Ask recruiters about the job market, salary ranges for people with your experience and good skills to learn.
- Review your connections’ companies, review posted jobs and ask for introductions from your connections (let them know why the company is awesome, why you’re awesome and why you want to work there).
Contracting: try it during the first decade of your career.
- It’s easier than applying for a full-time job given you’re easier to let go.
- It will keep your skills sharp if you want to find clients.
- If/when you’re an employee again, job hunting won’t feel as scary.
- You will strengthen your network by being able to refer former colleagues.
- Contracting can be more lucrative on a per-hour basis.
- Contracting via an agency is easier (you avoid sales and accounting) but it pays less.
- Direct contracting is harder but you’ll learn beyond software development (sales, customer support, marketing, invoicing and chasing payments). It leads to more control over the clients you work with and more income. You may spend as much as 50% of your time on non-billable work such as seeking new opportunities: your rate needs to reflect this.
Engineering management: if you move to a management position, be prepared to be a novice again as the skill set involved is not the same.
- You should understand the code but keep out of the critical path.
- You shouldn’t make technical decisions.
- You are here to enable teams to do great work.
- The fun, technical stuff should only be done during hackathons.
- Be clear about what you want and maintain the right set of skills so you can keep doing what you enjoy the most.
Someday, you won’t want to code for a living: becoming a manager gives you leverage to have more impact in the world.
- Impact can be achieved through writing, project management, product management, speaking, starting a business, mentoring, leading a team, managing, teaching, architecting and consulting. Notice that coding is not the primary output.

Community

Building a community/network puts you in a situation where you can help people help others.
Meetups: find one on meetup.com.
- It will expose you to new ideas you can bring to your job.
- You can have professional conversations with low stakes.
- It gives you a way to practice talking to new people and make friends.
- It provides a network outside of your coworkers should you need to find a new job.
Conversational hooks: give some details about where you work and what projects you have been working on to give the chance to the other person to steer the conversation in the direction they want. Flip the question to ask people to talk about themselves (most people like to do that).
- Don’t make transactional conversations: find something interesting to talk about.
Online tech communities:
- Sign up for an email list related to the technologies you are interested in. Sign up for notifications on projects. You can follow project contributors on Twitter or other social media places.
- For something more general, have a look on Slack, forums, IRC channels, Facebook groups and so on. Slashdot, Hacker News, Reddit, Stack Overflow are other good options.
You get what you give:
- Offering to help makes you more empathetic and aware of other people’s needs.
- It feels good to help.
- You become less arrogant.
- You help build the positivity of the community.
- People will be quicker to recommend you for a job.
- It improves your sense of self-worth and confidence.
Build your work community:
- Use LinkedIn.
- Never leave a job on bad terms. Give the requisite notice, document your work and prepare for a hand off.
- Keep in touch with past coworkers, even if it’s just to leave a note on their work anniversary.
Three daily mantras:
- Surround yourself with people smarter than you.
- Build community and give without expecting anything in return.
- Listen to your gut, without exception.
Build a personal board of advisors.
- Some issues you can discuss with them that aren’t topics for current coworkers:
  - Someone under your supervision is not succeeding;
  - You have an issue with your manager that you’re not sure how to solve;
  - You are evaluating job offers.
- Make sure to keep these relationships fresh and offer to help too.
- This circle shifts over time: a new developer doesn’t have the same questions that a team lead would have.

Conclusion

That’s it: we went through a short overview of a book I’ve enjoyed and recommend heartily. You can find more on the author’s website. You might also enjoy a follow-up book summary about The Effective Engineer. May you live this knowledge!

sglavoie.com – Tag: Best Practices

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

`var` vs. `:=`

`const`

`len`

`append`

`make`

`copy`