metalagman/go-google-style-decisions

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.

1. Naming Conventions

• Underscores: Do not use underscores in Go names (e.g., pkg_name or var_name).
  • 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