libsecp256k1/.claude/skills/golang/references/effective-go-summary.md

Effective Go - Key Points Summary

Source: https://go.dev/doc/effective_go

Formatting

• Use gofmt to automatically format your code
• Indentation: use tabs
• Line length: no strict limit, but keep reasonable
• Parentheses: Go uses fewer parentheses than C/Java

Commentary

• Every package should have a package comment
• Every exported name should have a doc comment
• Comments should be complete sentences
• Start comments with the name of the element being described

Example:

// Package regexp implements regular expression search.
package regexp

// Compile parses a regular expression and returns, if successful,
// a Regexp object that can be used to match against text.
func Compile(str string) (*Regexp, error) {

Names

Package Names

• Short, concise, evocative
• Lowercase, single-word
• No underscores or mixedCaps
• Avoid stuttering (e.g., bytes.Buffer not bytes.ByteBuffer)

Getters/Setters

• Getter: Owner() not GetOwner()
• Setter: SetOwner()

Interface Names

• One-method interfaces use method name + -er suffix
• Examples: Reader, Writer, Formatter, CloseNotifier

MixedCaps

• Use MixedCaps or mixedCaps rather than underscores

Semicolons

• Lexer automatically inserts semicolons
• Never put opening brace on its own line

Control Structures

If

if err := file.Chmod(0664); err != nil {
    log.Print(err)
    return err
}

Redeclaration

f, err := os.Open(name)
// err is declared here

d, err := f.Stat()
// err is redeclared here (same scope)

For

// Like a C for
for init; condition; post { }

// Like a C while
for condition { }

// Like a C for(;;)
for { }

// Range over array/slice/map/channel
for key, value := range oldMap {
    newMap[key] = value
}

// If you only need the key
for key := range m {
    // ...
}

// If you only need the value
for _, value := range array {
    // ...
}

Switch

• No automatic fall through
• Cases can be expressions
• Can switch on no value (acts like if-else chain)

switch {
case '0' <= c && c <= '9':
    return c - '0'
case 'a' <= c && c <= 'f':
    return c - 'a' + 10
case 'A' <= c && c <= 'F':
    return c - 'A' + 10
}

Type Switch

switch t := value.(type) {
case int:
    fmt.Printf("int: %d\n", t)
case string:
    fmt.Printf("string: %s\n", t)
default:
    fmt.Printf("unexpected type %T\n", t)
}

Functions

Multiple Return Values

func (file *File) Write(b []byte) (n int, err error) {
    // ...
}

Named Result Parameters

• Named results are initialized to zero values
• Can be used for documentation
• Enable naked returns

func ReadFull(r Reader, buf []byte) (n int, err error) {
    for len(buf) > 0 && err == nil {
        var nr int
        nr, err = r.Read(buf)
        n += nr
        buf = buf[nr:]
    }
    return
}

Defer

• Schedules function call to run after surrounding function returns
• LIFO order
• Arguments evaluated when defer executes

func trace(s string) string {
    fmt.Println("entering:", s)
    return s
}

func un(s string) {
    fmt.Println("leaving:", s)
}

func a() {
    defer un(trace("a"))
    fmt.Println("in a")
}

Data

Allocation with new

• new(T) allocates zeroed storage for new item of type T
• Returns *T
• Returns memory address of newly allocated zero value

p := new(int)   // p is *int, points to zeroed int

Constructors and Composite Literals

func NewFile(fd int, name string) *File {
    if fd < 0 {
        return nil
    }
    return &File{fd: fd, name: name}
}

Allocation with make

• make(T, args) creates slices, maps, and channels only
• Returns initialized (not zeroed) value of type T (not *T)

make([]int, 10, 100)   // slice: len=10, cap=100
make(map[string]int)   // map
make(chan int, 10)     // buffered channel

Arrays

• Arrays are values, not pointers
• Passing array to function copies the entire array
• Array size is part of its type

Slices

• Hold references to underlying array
• Can grow dynamically with append
• Passing slice passes reference

Maps

• Hold references to underlying data structure
• Passing map passes reference
• Zero value is nil

Printing

• %v - default format
• %+v - struct with field names
• %#v - Go syntax representation
• %T - type
• %q - quoted string

Initialization

Constants

• Created at compile time
• Can only be numbers, characters, strings, or booleans

init Function

• Each source file can have init() function
• Called after package-level variables initialized
• Used for setup that can't be expressed as declarations

func init() {
    // initialization code
}

Methods

Pointers vs. Values

• Value methods can be invoked on pointers and values
• Pointer methods can only be invoked on pointers

Rule: Value methods can be called on both values and pointers, but pointer methods should only be called on pointers (though Go allows calling on addressable values).

type ByteSlice []byte

func (slice ByteSlice) Append(data []byte) []byte {
    // ...
}

func (p *ByteSlice) Append(data []byte) {
    slice := *p
    // ...
    *p = slice
}

Interfaces and Other Types

Interfaces

• A type implements an interface by implementing its methods
• No explicit declaration of intent

Type Assertions

value, ok := str.(string)

Type Switches

switch v := value.(type) {
case string:
    // v is string
case int:
    // v is int
}

Generality

• If a type exists only to implement an interface and will never have exported methods beyond that interface, there's no need to export the type itself

The Blank Identifier

Unused Imports and Variables

import _ "net/http/pprof"  // Import for side effects

Interface Checks

var _ json.Marshaler = (*RawMessage)(nil)

Embedding

Composition, not Inheritance

type ReadWriter struct {
    *Reader  // *bufio.Reader
    *Writer  // *bufio.Writer
}

Concurrency

Share by Communicating

• Don't communicate by sharing memory; share memory by communicating
• Use channels to pass ownership

Goroutines

• Cheap: small initial stack
• Multiplexed onto OS threads
• Prefix function call with go keyword

Channels

• Allocate with make
• Unbuffered: synchronous
• Buffered: asynchronous up to buffer size

ci := make(chan int)            // unbuffered
cj := make(chan int, 0)         // unbuffered
cs := make(chan *os.File, 100)  // buffered

Channels of Channels

type Request struct {
    args        []int
    f           func([]int) int
    resultChan  chan int
}

Parallelization

const numCPU = runtime.NumCPU()
runtime.GOMAXPROCS(numCPU)

Errors

Error Type

type error interface {
    Error() string
}

Custom Errors

type PathError struct {
    Op   string
    Path string
    Err  error
}

func (e *PathError) Error() string {
    return e.Op + " " + e.Path + ": " + e.Err.Error()
}

Panic

• Use for unrecoverable errors
• Generally avoid in library code

Recover

• Called inside deferred function
• Stops panic sequence
• Returns value passed to panic

func server(workChan <-chan *Work) {
    for work := range workChan {
        go safelyDo(work)
    }
}

func safelyDo(work *Work) {
    defer func() {
        if err := recover(); err != nil {
            log.Println("work failed:", err)
        }
    }()
    do(work)
}

A Web Server Example

package main

import (
    "fmt"
    "log"
    "net/http"
)

type Counter struct {
    n int
}

func (ctr *Counter) ServeHTTP(w http.ResponseWriter, req *http.Request) {
    ctr.n++
    fmt.Fprintf(w, "counter = %d\n", ctr.n)
}

func main() {
    ctr := new(Counter)
    http.Handle("/counter", ctr)
    log.Fatal(http.ListenAndServe(":8080", nil))
}