Engineering Standards#

This is a living document. All contributors must read and follow these standards. The AI agents working on this project also consume this document to inform code generation — keep it current and comprehensive.

General principles#

• Write code as if the person who will maintain it is a violent psychopath who knows where you live.
• Prioritize readability and maintainability over cleverness or brevity.
• Follow established language conventions unless an explicit standard in this document overrides them.
• Go first. Minimize external dependencies.
• No Python or Node.js unless absolutely necessary for a task that cannot be done in Go. Document any exceptions.
• Variable names must be descriptive. Favor long, unambiguous names over short ones. Avoid abbreviations.
• Keep documentation up to date. It is consumed by both humans and AI contributors.

Go coding style#

Formatting#

All Go code must be formatted with gofumpt (default settings) before committing. gofumpt is a stricter superset of gofmt.

Add blank lines between logical sections of code to improve readability.

Bad:

func sumAll(numbers []int) int {
    sum := 0
    for _, num := range numbers {
        sum += num
    }
    return sum
}

Good:

// sumAll takes a slice of integers and returns their total sum.
func sumAll(numbers []int) int {
    // initialize sum to 0 before iterating through the numbers
    sum := 0

    // iterate through each number in the input slice and add it to sum
    for _, num := range numbers {
        sum += num
    }

    // return the final computed sum after processing all numbers
    return sum
}

Comments#

Write comments that explain the why, not the what. The reader should be able to understand program flow and intent without reading the code itself.

Bad:

func GetUserByID(id int) (*User, error) {
    ok, user := users[id]
    if !ok {
        return nil, fmt.Errorf("user with ID %d not found", id)
    }
    return user, nil
}

Good:

// GetUserByID retrieves a user by their unique ID.
// It returns an error if the user is not found.
func GetUserByID(id int) (*User, error) {
    // attempt to retrieve the user from the users map
    ok, user := users[id]
    if !ok {
        // user not found, return an error with the ID for context
        return nil, fmt.Errorf("user with ID %d not found", id)
    }

    // user found, return the user object and no error
    return user, nil
}