go-google-style-decisions

This skill provides expert guidance on the "Decisions" portion of the Google Go Style Guide. It focuses on the specific choices and trade-offs made to ensure consistency, readability, and maintainability across large Go codebases.

Core Mandates

1. Clarity over Conciseness: While Go favors brevity, never sacrifice clarity.
2. Consistency is Key: Adhere to established patterns in the codebase.
3. Idiomaticity: Follow Go-specific patterns (e.g., error handling, interface usage).
4. No Underscores: Avoid underscores in names except in specifically allowed cases (tests, generated code).

Developer Workflow

1. Design: Plan APIs following the "Least Mechanism" principle.
2. Implement: Write code adhering to the style decisions detailed below.
3. Lint: Use golangci-lint or go vet to catch common style violations.
4. Test: Include runnable examples in _test.go files for public APIs.
5. Review: Ensure changes align with the "Core Principles" of clarity and consistency.

Detailed Guidance

For the complete guide, consult [references/decisions.md](references/decisions.md).

1. Naming Conventions

• Underscores: Do not use underscores in Go names (e.g., pkgname or varname).

Exceptions*: _test.go files, generated code, and low-level interop.

• Package Names:

Short, lowercase, single word. No util or common. Avoid common variable names (e.g., user as a package name if user is a common variable).

• Receiver Names:

Short (1-2 letters). Consistently used throughout the type's methods. * Usually an abbreviation of the type (e.g., c for Client).

• Constant Names:

Use MixedCaps (e.g., ExportedConst, internalConst). Do NOT use ALL_CAPS or kPrefix.

• Initialisms:

* Maintain consistent casing (e.g., HTTPClient, urlPath, XMLParser).

• Getters:

Omit Get prefix (e.g., use obj.Field() instead of obj.GetField()). Use Get only if the method is truly "getting" something that isn't a simple field (e.g., GetURL).

• Variable Names:

Length should be proportional to scope. Short names for small scopes (e.g., i in a loop), more descriptive names for larger scopes. Omit types from names (e.g., users instead of userSlice).

2. Commentary

• Line Length: Aim for ~80 characters. Wrap long comments.
• Doc Comments: Every top-level exported name MUST have a doc comment.

Must start with the name of the object. Must be a complete sentence.

• Examples: Provide ExampleXxx functions in test files to document public APIs.

3. Error Handling

• Error as Last Return: Always return error as the final value.
• Returning Nil: Return nil for the error value on success.
• Error Interfaces: Exported functions should return the error interface, not a concrete type.
• Error Strings:

No capitalization (unless proper nouns/acronyms). No trailing punctuation.

• Indentation: Handle errors early and return/continue. Keep the "happy path" at the minimal level of indentation.
• No In-band Errors: Do not use special values (like -1) to signal errors. Use (value, error) or (value, ok).

4. Language Constructs

• Composite Literals: Use them for struct initialization. Always specify field names when the struct is from another package.
• Nil Slices: Prefer var s []int (nil slice) over s := []int{} (empty slice).

* Avoid APIs that distinguish between nil and empty slices.

• Braces:

Closing braces should align with the opening statement. Avoid "cuddling" (e.g., if err != nil { ... } else { ... } is fine, but don't over-compact).

• Function Formatting: Keep signatures on one line if possible. If they must wrap, indent the arguments.

5. Panic and Recovery

• Avoid Panic: Do not use panic for normal error handling.
• Exceptional Only: Use panic only for truly unrecoverable states (e.g., internal invariant failure).
• Program Termination: Use log.Exit or log.Fatal (which calls os.Exit) only in main or init functions.
• MustXYZ: Helper functions that terminate the program on failure should be prefixed with Must (e.g., template.Must).

6. Copying

• Structs with Locks: Be extremely careful copying structs that contain sync.Mutex or other synchronization primitives.
• Pointer Receivers: If a type has methods with pointer receivers, avoid copying values of that type.

References

• Google Go Style Decisions