xe-go-style

Xe's Go Style Guide

Write Go code following the conventions and patterns used by Xe Iaso.

Project Structure

├── cmd/            # Main applications (each subdirectory is a binary)
│   ├── x/          # CLI with subcommands
│   │   ├── main.go
│   │   └── cmd/    # Subcommand packages
│   └── sakurajima/ # Service binaries
│       ├── main.go
│       └── internal/  # Command-specific internal packages
├── internal/       # Private packages shared across commands
├── web/            # Web-related services and API clients
└── gen/            # Generated code (protobuf)

Package naming: lowercase, single words preferred (slog, flagenv, kahless).

CLI Pattern (CRITICAL)

All command-line tools MUST call flagenv.Parse() and then flag.Parse().

package main

import (
    "flag"

    "github.com/facebookgo/flagenv"
)

var (
    bind  = flag.String("bind", ":8080", "HTTP bind address")
    dbLoc = flag.String("db-loc", "", "Database location")
)

func main() {
    flagenv.Parse()
    flag.Parse()
}

Configuration loading order: flags → env vars (flagenv) → flags (final override).

Subcommands

Use github.com/google/subcommands for subcommand-based CLIs:

package main

import (
    "context"
    "flag"
    "os"

    "github.com/facebookgo/flagenv"
    "github.com/google/subcommands"
)

func main() {
    flagenv.Parse()

    subcommands.Register(subcommands.HelpCommand(), "")
    subcommands.Register(subcommands.FlagsCommand(), "")
    subcommands.Register(subcommands.CommandsCommand(), "")
    subcommands.Register(&serveCmd{}, "")
    subcommands.Register(&versionCmd{}, "")

    os.Exit(int(subcommands.Execute(context.Background())))
}

type serveCmd struct {
    dbLoc string
}

func (c *serveCmd) Name() string     { return "serve" }
func (c *serveCmd) Synopsis() string { return "Start the server" }
func (c *serveCmd) Usage() string {
    return "serve [flags]\nStart the HTTP server.\n"
}

func (c *serveCmd) SetFlags(f *flag.FlagSet) {
    f.StringVar(&c.dbLoc, "db-loc", "", "Database location")
}

func (c *serveCmd) Execute(ctx context.Context, f *flag.FlagSet, args ...interface{}) subcommands.ExitStatus {
    // Implementation
    return subcommands.ExitSuccess
}