golang-style-guide
Conventions and best practices for writing readable, maintainable Go code based on the Google Go Style Guide. Use this skill when: Writing new Go packages, services, or command-line tools. Refactoring
SKILL.mdskills/golang/golang-style-guide/SKILL.md
GitHubSkill: Go (Google Style Guide)
Overview
This skill implements conventions from the Google Go Style Guide.
The goal is to produce Go code that is:
- Clear and easy to read
- Simple and idiomatic
- Concise with a high signal-to-noise ratio
- Maintainable over time
- Consistent with the broader Go ecosystem
Readable code is prioritized over clever or complex solutions.
Core Principles
1. Clarity
Code must be easy to understand. Prefer self-describing names. Comments should explain why, not what.
2. Simplicity
Use the simplest approach. Prefer core language features and the standard library. Avoid unnecessary abstraction.
3. Concision
High signal-to-noise ratio. Reduce repetition and boilerplate. Use common Go idioms.
4. Maintainability
Easy to modify correctly. Clear structure, low coupling, and meaningful tests.
Formatting & Imports
Always Use gofmt
All Go source code must be formatted with gofmt.
Import Grouping
Imports should be organized into two groups:
- Standard library packages
- Third-party and project-specific packages
Separate these two groups with a blank line. Within each group, imports should be sorted alphabetically.
Example:
import (
"fmt"
"os"
"github.com/google/uuid"
"myproject/internal/pkg"
)
Naming
MixedCaps & Initialisms
Go uses MixedCaps (camelCase or PascalCase).
Initialisms (acronyms) should have consistent casing. URL should be URL or url, never Url. ID should be ID or id, never Id.
| Correct | Incorrect |
|---|---|
XMLHTTPRequest |
XmlHttpRequest |
userID |
userId |
appID |
appId |
gRPC |
grpc |
Package Names
- Short, all-lowercase, single word.
- No underscores or MixedCaps.
- Avoid names likely to be shadowed (e.g., use
usercountinstead ofcount). - Rename imports if the original package name contains underscores.
Receiver Names
- Short (1-2 letters), usually an abbreviation of the type.
- Be consistent within a type's method set.
- Avoid generic names like
me,this, orself.
Example:
func (tr *Tray) Activate() { ... }
func (ri *ResearchInfo) GetDetails() { ... }
Receiver Types (Value vs. Pointer)
- Use a pointer receiver if the method needs to mutate the receiver.
- Use a pointer receiver if the receiver is a large struct or array.
- Use a value receiver for small, immutable types (like basic types or small structs with no pointers).
- Consistency: If any method of a type has a pointer receiver, all methods should probably have pointer receivers.
Comments & Documentation
Doc Comments
- Every exported symbol should have a doc comment.
- Comments must be complete sentences starting with the name of the symbol.
- Use the Go doc comment style.
Example:
// A Server handles serving quotes from the works of Shakespeare.
type Server struct { ... }
// Encode writes the JSON encoding of req to w.
func Encode(w io.Writer, req *Request) { ... }
Error Handling
Error Strings
- Error strings should not be capitalized.
- Error strings should not end with punctuation.
- This ensures they flow well when wrapped or logged.
Example:
// Good
return fmt.Errorf("something bad happened")
// Bad
return fmt.Errorf("Something bad happened.")
Testing
Maintain a comprehensive test suite.
- Use table-driven tests for complex logic.
- Tests should be deterministic and provide clear failure messages.
- Focus on behavior over implementation details.
Consistency
Consistency within a package is paramount. If the style guide is silent, follow the existing patterns in the codebase.
Summary
- Clarity over cleverness.
- Standard library over dependencies.
- Idiomatic patterns (errors, receivers, naming).
- Consistency with the Google Go Style Guide.