samber/cc-skills-golang / skills/golang-safety
golang-safety
VerifiedDefensive Golang coding against accidental bugs — nil panics, typed-nil interfaces, `append` backing-array aliasing, silent int64-to-int32 truncation, float `==` comparison, `defer` inside loops, defensive copies of slices and maps, and usable zero values. Use when a Go program panics on a nil map write or nil pointer dereference, when reviewing code for nil-safety, numeric conversion overflow, or resource lifecycle, or when designing a type whose zero value must be safe. Not for designing concurrent access with goroutines, channels, or sync primitives (→ See `samber/cc-skills-golang@golang-concurrency` skill), not for exploitable vulnerabilities such as injection, weak crypto, or leaked secrets (→ See `samber/cc-skills-golang@golang-security` skill), and not for debugging an already-failing program (→ See `samber/cc-skills-golang@golang-troubleshooting` skill).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.5 KB |
| evals/evals.json | config | 47.4 KB |
| references/nil-safety.md | markdown | 5.6 KB |
| references/slice-map-safety.md | markdown | 6.2 KB |
references/nil-safety.md
View on GitHub# Nil Safety Deep Dive
## Table of Contents
- [Nil Pointer Receivers](#nil-pointer-receivers)
- [Designing nil-safe receivers](#designing-nil-safe-receivers)
- [Nil Function Values](#nil-function-values)
- [Default function pattern](#default-function-pattern)
- [Nil and Error Comparisons](#nil-and-error-comparisons)
- [Returning nil error correctly](#returning-nil-error-correctly)
- [Checking error chains with nil](#checking-error-chains-with-nil)
- [Nil in Generic Code](#nil-in-generic-code)
- [The `comparable` constraint and nil](#the-comparable-constraint-and-nil)
- [Nil checks with unconstrained type parameters](#nil-checks-with-unconstrained-type-parameters)
- [Patterns for Nil-Safe APIs](#patterns-for-nil-safe-apis)
- [Constructor with defaults](#constructor-with-defaults)
- [Lazy initialization for zero-value usability](#lazy-initialization-for-zero-value-usability)
## Nil Pointer Receivers
MUST check for nil before calling methods on pointer receivers from external sources. A method call on a nil pointer does not always panic — it depends on whether the method dereferences the receiver:
```go
type Logger struct {
prefix string
}
// ✓ Safe on nil but NEVER do that — does not dereference l
func (l *Logger) IsEnabled() bool {
return l != nil
}
// ✗ Panics on nil — dereferences l to access prefix
func (l *Logger) Log(msg string) {
fmt.Printf("[%s] %s\n", l.prefix, msg)
}
var l *Logger
l.IsEnabled() // false — works fine
l.Log("test") // panic: nil pointer dereference
```
Anyway, NEVER call a method on a nil pointer.
### Designing nil-safe receivers
When a nil receiver is a valid state (e.g., optional components), guard against it explicitly:
```go
func (l *Logger) Log(msg string) {
if l == nil {
return // silently skip if no logger configured
}
fmt.Printf("[%s] %s\n", l.prefix, msg)
}
```
This pattern is useful for optional dependencies, but use it sparingly — a nil receiver usually signals a bug, not an intentional state. Document when nil is an expected value.
## Nil Function Values
NEVER rely on nil function values — always validate before calling. Calling a nil `func` variable panics:
```go
// ✗ Bad — panics if callback was never set
type Worker struct {
onComplete func(result string)
}
func (w *Worker) Finish(result string) {
w.onComplete(result) // panic if onComplete is nil
}
// ✓ Good — check before calling
func (w *Worker) Finish(result string) {
if w.onComplete != nil {
w.onComplete(result)
}
}
```
### Default function pattern
Provide a no-op default to avoid nil checks at every call site:
```go
func NewWorker(opts ...Option) *Worker {
w := &Worker{
onComplete: func(string) {}, // no-op default
}
for _, opt := range opts {
opt(w)
}
return w
}
```
## Nil and Error Comparisons
### Returning nil error correctly
Interface comparisons with nil MUST account for the nil interface trap. A function returning `error` must return the untyped `nil`, not a typed nil pointer:
```go
// ✗ Bad — returns non-nil error interface
func validate(s string) error {
var err *ValidationError // typed nil
if s == "" {
err = &ValidationError{Field: "name"}
}
return err // even when err is nil, interface is non-nil
}
// ✓ Good — return nil explicitly
func validate(s string) error {
if s == "" {
return &ValidationError{Field: "name"}
}
return nil
}
```
### Checking error chains with nil
`errors.Is(err, nil)` returns `true` only if `err` is truly nil. It does not help with the nil interface trap — the trap occurs before the error reaches `errors.Is`.
## Nil in Generic Code
### The `comparable` constraint and nil
Generic code MUST handle the zero value of type parameters correctly. Type parameters constrained by `comparable` can be compared with `==`, but nil is not always a valid value:
```go
// ✗ Confusing — T may or may not be nillable
func IsZero[T comparable](v T) bool {
var zero T
return v == zero // works, but "zero" for *Foo is nil, for int is 0
}
// ✓ Better — be explicit about what "empty" means
func IsNil[T interface{ ~*U }, U any](v T) bool {
return v == nil
}
```
### Nil checks with unconstrained type parameters
You cannot compare an unconstrained type parameter to nil:
```go
// ✗ Does not compile
func Check[T any](v T) bool {
return v == nil // compile error: cannot compare T with nil
}
// ✓ Good — use reflect or constrain to pointer types
func IsNilPtr[T any](v *T) bool {
return v == nil
}
```
## Patterns for Nil-Safe APIs
### Constructor with defaults
Require initialization through a constructor, making the zero value impossible for external callers:
```go
type Client struct {
httpClient *http.Client
baseURL string
}
// Constructor guarantees non-nil fields
func NewClient(baseURL string) *Client {
return &Client{
httpClient: http.DefaultClient,
baseURL: baseURL,
}
}
```
### Lazy initialization for zero-value usability
When you want the zero value to be usable but need internal resources:
```go
type Cache struct {
mu sync.Mutex
data map[string]any
}
func (c *Cache) Get(key string) (any, bool) {
c.mu.Lock()
defer c.mu.Unlock()
if c.data == nil {
return nil, false
}
v, ok := c.data[key]
return v, ok
}
func (c *Cache) Set(key string, val any) {
c.mu.Lock()
defer c.mu.Unlock()
if c.data == nil {
c.data = make(map[string]any)
}
c.data[key] = val
}
```
→ See `samber/cc-skills-golang@golang-error-handling` skill for nil error comparison pitfalls.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |