Maps

Canonical guidance

• use maps for keyed lookup and set-like membership checks
• remember that reading from a nil map is okay but writing is not
• synchronize all concurrent access when writes may happen

Use when

• indexing by ID
• deduplication
• counting and grouping

Avoid

• depending on iteration order
• concurrent mutation with no synchronization
• concurrent read/write with no synchronization
• maps where a slice or struct models the domain more clearly

Preferred pattern

seen := map[string]struct{}{}

if _, ok := seen[id]; !ok {
	seen[id] = struct{}{}
}

Anti-pattern

• building behavior that accidentally depends on map iteration order

Explanation: This anti-pattern is tempting because test runs can look stable, but order dependencies tend to fail when the data or runtime changes.

Why

• maps are powerful, but their mutation and ordering semantics matter