diff --git a/style.md b/style.md index 6dd0951d..53d08998 100644 --- a/style.md +++ b/style.md @@ -75,8 +75,9 @@ row before the line. - [Performance](#performance) - [Prefer strconv over fmt](#prefer-strconv-over-fmt) - [Avoid string-to-byte conversion](#avoid-string-to-byte-conversion) - - [Prefer Specifying Map Capacity Hints](#prefer-specifying-map-capacity-hints) - - [Prefer Specifying Slice Capacity for Appending](#prefer-specifying-slice-capacity-for-appending) + - [Prefer Specifying Container Capacity](#prefer-specifying-container-capacity) + - [Specifying Map Capacity Hints](#specifying-map-capacity-hints) + - [Specifying Slice Capacity](#specifying-slice-capacity) - [Style](#style) - [Be Consistent](#be-consistent) - [Group Similar Declarations](#group-similar-declarations) @@ -1722,7 +1723,13 @@ BenchmarkGood-4 500000000 3.25 ns/op -### Prefer Specifying Map Capacity Hints +### Prefer Specifying Container Capacity + +Specify container capacity where possible in order to allocate memory for the +container up front. This minimizes subsequent allocations (by copying and +resizing of the container) as elements are added. + +#### Specifying Map Capacity Hints Where possible, provide capacity hints when initializing maps with `make()`. @@ -1733,9 +1740,12 @@ make(map[T1]T2, hint) Providing a capacity hint to `make()` tries to right-size the map at initialization time, which reduces the need for growing -the map and allocations as elements are added to the map. Note -that the capacity hint is not guaranteed for maps, so adding -elements may still allocate even if a capacity hint is provided. +the map and allocations as elements are added to the map. + +Note that, unlike slices, map capacity hints do not guarantee complete, +preemptive allocation, but are used to approximate the number of hashmap buckets +required. Consequently, allocations may still occur when adding elements to the +map, even up to the specified capacity. @@ -1777,9 +1787,20 @@ allocations at assignment time.
BadGood
-### Prefer Specifying Slice Capacity for Appending +#### Specifying Slice Capacity + +Where possible, provide capacity hints when initializing slices with `make()`, +particularly when appending. + +```go +make([]T, length, capacity) +``` -Where possible, provide a capacity value to `make()` when initializing a slice for appending. +Unlike maps, slice capacity is not a hint: the compiler will allocate enough +memory for the capacity of the slice as provided to `make()`, which means that +subsequent `append()` operations will incur zero allocations (until the length +of the slice matches the capacity, after which any appends will require a resize +to hold additional elements).
BadGood