go-standards-audit

Go Standards Audit

Gopher Guides coding standards enforcement. Validates Go projects against professional standards for documentation, concurrency, dependencies, and project structure.

API Integration (Optional)

If GOPHER_GUIDES_API_KEY is set, verify it:

curl -s -H "Authorization: Bearer $GOPHER_GUIDES_API_KEY" \
  https://gopherguides.com/api/gopher-ai/me

If not set, local analysis tools (go vet, staticcheck, golangci-lint) still provide comprehensive analysis. Set the key for enhanced API-powered insights. Get your key at gopherguides.com.

What It Checks

1. Documentation Completeness (Godoc)

Every exported type, function, method, and package should have proper documentation:

# Find exported symbols missing documentation
# Look for exported funcs/types without preceding comments
grep -rn "^func [A-Z]" --include="*.go" | while read line; do
  file=$(echo "$line" | cut -d: -f1)
  linenum=$(echo "$line" | cut -d: -f2)
  prevline=$((linenum - 1))
  prev=$(sed -n "${prevline}p" "$file")
  if [[ ! "$prev" =~ ^// ]]; then
    echo "Missing godoc: $line"
  fi
done

Standards:

• Package comments in doc.go for non-trivial packages
• All exported names have comments starting with the name
• Comments are complete sentences
• Examples in _test.go files for complex APIs

2. Concurrency Patterns

Review goroutine usage for correctness:

• Context propagation — All long-running functions accept context.Context
• Goroutine lifecycle — Every goroutine has a clear exit path
• Channel usage — Buffered vs unbuffered chosen intentionally
• Mutex vs Channel — Mutexes for state, channels for coordination
• errgroup — Used for coordinating multiple goroutines
• Race detection — go test -race ./... passes

# Run race detector
go test -race -count=1 ./...

# Check for common concurrency issues
go vet -copylocks ./...

3. Dependency Management

# Check for outdated dependencies
go list -m -u all

# Verify module integrity
go mod verify

# Check for unused dependencies
go mod tidy -diff

# Review direct dependencies
go list -m -f '{{if not .Indirect}}{{.Path}} {{.Version}}{{end}}' all