Best Practices and Code Organization

The 10,000-Line main.go That Made Me Cry

It was my third month at the company when I inherited "the project." A microservice that had grown from a weekend prototype to a critical production system. The entire codebase was in one file: 10,427 lines of main.go.

package main

import (
    // 47 imports...
)

// 23 global variables
var db *sql.DB
var cache *redis.Client
var logger *log.Logger
// ... 20 more

// 147 functions in no particular order
func handleUserCreate(w http.ResponseWriter, r *http.Request) { }
func validateEmail(email string) bool { }
func connectDatabase() error { }
func processPayment(amount float64) error { }
// ... 143 more functions

Adding a feature meant scrolling through thousands of lines. Finding related functions was impossible. Testing? Forget it - everything depended on global state.

I spent two weeks refactoring. The result:

project/
├── cmd/
│   └── server/
│       └── main.go              # 47 lines
├── internal/
│   ├── user/
│   │   ├── handler.go          # HTTP handlers
│   │   ├── service.go          # Business logic
│   │   └── repository.go       # Database access
│   ├── payment/
│   │   ├── handler.go
│   │   ├── service.go
│   │   └── repository.go
│   └── common/
│       ├── validator.go
│       └── response.go
├── pkg/
│   └── logger/
│       └── logger.go
└── go.mod

The impact:

• 47-line main.go (down from 10,427)

• 90% test coverage (up from 0%)

• 3-minute onboarding for new developers (down from days)

• Zero merge conflicts (everyone works in different packages)

That refactoring taught me: code organization isn't optional. This article covers the patterns that saved the project.

---

Standard Go Project Layout

The Go community has converged on a standard project structure.

Small Project

myproject/
├── main.go              # Entry point
├── handlers.go          # HTTP handlers
├── service.go           # Business logic
├── repository.go        # Database code
├── models.go            # Data types
└── go.mod

Medium Project

myproject/
├── cmd/
│   └── server/
│       └── main.go      # Entry point
├── internal/            # Private application code
│   ├── handlers/
│   ├── service/
│   └── repository/
├── pkg/                 # Public library code
│   └── logger/
├── go.mod
└── README.md

Large Project (Standard Layout)

myproject/
├── cmd/
│   ├── server/          # Main server application
│   │   └── main.go
│   ├── worker/          # Background worker
│   │   └── main.go
│   └── migration/       # Database migration tool
│       └── main.go
├── internal/            # Private application code
│   ├── user/
│   │   ├── handler.go
│   │   ├── service.go
│   │   ├── repository.go
│   │   └── model.go
│   ├── auth/
│   │   ├── handler.go
│   │   ├── service.go
│   │   └── middleware.go
│   └── common/
│       ├── errors.go
│       └── response.go
├── pkg/                 # Public library code (can be imported by other projects)
│   ├── logger/
│   │   └── logger.go
│   ├── database/
│   │   └── postgres.go
│   └── validator/
│       └── validator.go
├── api/                 # API definitions (OpenAPI/Swagger)
├── web/                 # Web assets (if applicable)
├── scripts/             # Build/deploy scripts
├── deployments/         # Docker, Kubernetes configs
│   ├── Dockerfile
│   └── kubernetes/
├── docs/                # Documentation
├── .gitignore
├── go.mod
├── go.sum
├── Makefile
└── README.md

Directory Purposes

cmd/: Application entry points. Each subdirectory is a separate executable.

internal/: Private application code. Cannot be imported by other projects.

pkg/: Public library code. Can be imported by other projects.

api/: API definitions, protocol definitions, OpenAPI specs.

web/: Web application assets (templates, static files).

scripts/: Build, install, analysis scripts.

deployments/: Deployment configs (Docker, Kubernetes, etc.).

docs/: Design documents, user documentation.

---

Package Organization Principles

Organize by Feature, Not Layer

Bad (organized by layer):

internal/
├── handlers/
│   ├── user_handler.go
│   ├── post_handler.go
│   └── comment_handler.go
├── services/
│   ├── user_service.go
│   ├── post_service.go
│   └── comment_service.go
└── repositories/
    ├── user_repository.go
    ├── post_repository.go
    └── comment_repository.go

Good (organized by feature):

internal/
├── user/
│   ├── handler.go
│   ├── service.go
│   ├── repository.go
│   └── model.go
├── post/
│   ├── handler.go
│   ├── service.go
│   ├── repository.go
│   └── model.go
└── comment/
    ├── handler.go
    ├── service.go
    ├── repository.go
    └── model.go

Benefits:

• Related code stays together

• Easier to find everything for a feature

• Clear boundaries between domains

• Easier to extract into microservices later

Small, Focused Packages

// Bad: Everything in one package
package app

type User struct { }
type Post struct { }
type Comment struct { }
func CreateUser() { }
func CreatePost() { }
func CreateComment() { }
// ... 100 more functions

// Good: Focused packages
package user
type User struct { }
func Create() { }
func Get() { }

package post
type Post struct { }
func Create() { }
func Get() { }

---

Naming Conventions

Package Names

Rules:

• Short, lowercase, single word

• No underscores or camelCase

• Match the directory name

• Be descriptive but concise

// Good
package user
package http
package auth
package logger

// Bad
package userPackage
package user_package
package users
package util  // Too generic

File Names

// Good
user.go
user_test.go
repository.go
handler.go

// Bad
UserRepository.go       // Don't capitalize
user-repository.go      // Use underscore, not dash
UserRepo.go            // Don't abbreviate unnecessarily

Variable Names

Short names for short scope:

// Good
for i := 0; i < 10; i++ { }

users := getUsers()
for _, u := range users { }

// Bad
for index := 0; index < 10; index++ { }

users := getUsers()
for _, user := range users { }  // 'u' is fine in short loop

Descriptive names for longer scope:

// Good
type UserRepository struct {
    database *sql.DB
    cache    *redis.Client
}

// Bad
type UserRepository struct {
    db *sql.DB
    c  *redis.Client
}

Function Names

Exported functions (public):

// Good - clear, descriptive
func CreateUser(name string) (*User, error) { }
func GetUserByID(id int) (*User, error) { }
func ValidateEmail(email string) bool { }

// Bad - abbreviations, unclear
func CrtUsr(name string) (*User, error) { }
func GetUsr(id int) (*User, error) { }
func VldEmail(email string) bool { }

Unexported functions (private):

// Good
func parseUserInput(input string) (string, error) { }
func validateAge(age int) bool { }

// Bad - don't need "private" prefix
func privateParseUserInput(input string) (string, error) { }

Constants

// Good
const (
    MaxRetries = 3
    DefaultTimeout = 30 * time.Second
)

// Bad - don't use ALL_CAPS
const (
    MAX_RETRIES = 3
    DEFAULT_TIMEOUT = 30
)

---

Go Tools

gofmt - Format Code

Automatically formats your code:

# Format single file
gofmt -w main.go

# Format all files
gofmt -w .

# Check without modifying
gofmt -d .

Never commit unformatted code. Use a pre-commit hook:

#!/bin/bash
# .git/hooks/pre-commit

if [ "$(gofmt -l .)" ]; then
    echo "Code is not formatted. Run: gofmt -w ."
    exit 1
fi

go vet - Check for Bugs

Analyzes code for common mistakes:

go vet ./...

Catches:

• Unreachable code

• Printf format errors

• Struct tag mistakes

• Shadowed variables

golint - Style Checker

# Install
go install golang.org/x/lint/golint@latest

# Run
golint ./...

Checks for:

• Exported types without comments

• Incorrect naming conventions

• Package comments

staticcheck - Advanced Linter

# Install
go install honnef.co/go/tools/cmd/staticcheck@latest

# Run
staticcheck ./...

More thorough than go vet. Catches:

• Unused code

• Inefficient code

• Potential bugs

golangci-lint - Meta Linter

Runs multiple linters at once:

# Install
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin

# Run
golangci-lint run

---

Code Review Checklist

Error Handling

// ✓ Good
result, err := doSomething()
if err != nil {
    return fmt.Errorf("failed to do something: %w", err)
}

// ✗ Bad
result, _ := doSomething()  // Ignoring errors

Resource Management

// ✓ Good
file, err := os.Open("config.json")
if err != nil {
    return err
}
defer file.Close()  // Always defer Close

// ✗ Bad
file, _ := os.Open("config.json")
// Forgot defer - resource leak!

Goroutine Leaks

// ✓ Good
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

go func() {
    select {
    case <-ctx.Done():
        return  // Exit point
    case result := <-ch:
        process(result)
    }
}()

// ✗ Bad
go func() {
    result := <-ch  // Blocks forever if no data
    process(result)
}()  // Goroutine leak!

Nil Checks

// ✓ Good
if user == nil {
    return errors.New("user is nil")
}
fmt.Println(user.Name)

// ✗ Bad
fmt.Println(user.Name)  // Panic if user is nil!

Interface Segregation

// ✓ Good - small, focused interfaces
type Reader interface {
    Read(p []byte) (n int, err error)
}

type Writer interface {
    Write(p []byte) (n int, err error)
}

// ✗ Bad - large interface
type Storage interface {
    Read(p []byte) (n int, err error)
    Write(p []byte) (n int, err error)
    Close() error
    Seek(offset int64, whence int) (int64, error)
    // 10 more methods...
}

---

Effective Go Principles

Accept Interfaces, Return Structs

// Good
func ProcessData(r io.Reader) (*Result, error) {
    // Accepts any Reader implementation
}

// Bad
func ProcessData(f *os.File) (*Result, error) {
    // Only accepts *os.File
}

Handle Errors, Don't Panic

// Good
func divide(a, b float64) (float64, error) {
    if b == 0 {
        return 0, errors.New("division by zero")
    }
    return a / b, nil
}

// Bad
func divide(a, b float64) float64 {
    if b == 0 {
        panic("division by zero")  // Don't panic!
    }
    return a / b
}

Panic only for:

• Truly unrecoverable errors

• Initialization failures

• Programmer errors (not user errors)

Use Context for Cancellation

// Good
func FetchData(ctx context.Context, url string) ([]byte, error) {
    req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
    // ...
}

// Bad
func FetchData(url string) ([]byte, error) {
    req, err := http.NewRequest("GET", url, nil)
    // No way to cancel!
}

Prefer Composition Over Inheritance

Go doesn't have inheritance. Use composition:

// Good - composition
type Logger struct {
    prefix string
}

type Service struct {
    logger Logger  // Has-a relationship
}

// Embedded struct
type TimestampedLogger struct {
    Logger  // Embeds Logger
}

---

Common Mistakes to Avoid

Mistake 1: Goroutines Without Exit

// ✗ Bad
func startWorker() {
    go func() {
        for {
            // Infinite loop, no exit
            doWork()
        }
    }()
}

// ✓ Good
func startWorker(ctx context.Context) {
    go func() {
        for {
            select {
            case <-ctx.Done():
                return  // Exit when context is cancelled
            default:
                doWork()
            }
        }
    }()
}

Mistake 2: Ignoring Error Returns

// ✗ Bad
json.Unmarshal(data, &result)

// ✓ Good
if err := json.Unmarshal(data, &result); err != nil {
    return fmt.Errorf("failed to unmarshal: %w", err)
}

Mistake 3: Pointer to Loop Variable

// ✗ Bad
var users []*User
for _, u := range userList {
    users = append(users, &u)  // All point to same address!
}

// ✓ Good
var users []*User
for _, u := range userList {
    userCopy := u
    users = append(users, &userCopy)
}

Mistake 4: Not Closing Channels

// ✗ Bad
func producer() <-chan int {
    ch := make(chan int)
    go func() {
        for i := 0; i < 10; i++ {
            ch <- i
        }
        // Forgot to close!
    }()
    return ch
}

// ✓ Good
func producer() <-chan int {
    ch := make(chan int)
    go func() {
        defer close(ch)  // Always close
        for i := 0; i < 10; i++ {
            ch <- i
        }
    }()
    return ch
}

Mistake 5: Race Conditions

// ✗ Bad
var counter int
for i := 0; i < 10; i++ {
    go func() {
        counter++  // Race condition!
    }()
}

// ✓ Good
var (
    counter int
    mu      sync.Mutex
)
for i := 0; i < 10; i++ {
    go func() {
        mu.Lock()
        counter++
        mu.Unlock()
    }()
}

Detect races:

go test -race ./...
go run -race main.go

---

Real Example: Refactored Project Structure

Before (10,000 lines in main.go)

package main

var db *sql.DB
var cache *redis.Client

func main() {
    db = connectDB()
    cache = connectCache()
    
    http.HandleFunc("/users", handleUsers)
    http.HandleFunc("/posts", handlePosts)
    http.ListenAndServe(":8080", nil)
}

func handleUsers(w http.ResponseWriter, r *http.Request) {
    // 200 lines of handler logic
}

func handlePosts(w http.ResponseWriter, r *http.Request) {
    // 200 lines of handler logic
}

// ... 143 more functions

After (organized structure)

cmd/server/main.go:

package main

import (
    "log"
    "myapp/internal/config"
    "myapp/internal/database"
    "myapp/internal/server"
)

func main() {
    cfg := config.Load()
    
    db, err := database.Connect(cfg.DatabaseURL)
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()
    
    srv := server.New(db)
    
    log.Printf("Starting server on %s", cfg.Port)
    log.Fatal(srv.Start(cfg.Port))
}

internal/user/handler.go:

package user

import (
    "encoding/json"
    "net/http"
)

type Handler struct {
    service *Service
}

func NewHandler(service *Service) *Handler {
    return &Handler{service: service}
}

func (h *Handler) Create(w http.ResponseWriter, r *http.Request) {
    var req CreateRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }
    
    user, err := h.service.Create(r.Context(), req.Name, req.Email)
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    
    json.NewEncoder(w).Encode(user)
}

internal/user/service.go:

package user

import "context"

type Service struct {
    repo *Repository
}

func NewService(repo *Repository) *Service {
    return &Service{repo: repo}
}

func (s *Service) Create(ctx context.Context, name, email string) (*User, error) {
    // Validation
    if name == "" {
        return nil, ErrInvalidName
    }
    
    // Business logic
    user := &User{
        Name:  name,
        Email: email,
    }
    
    return s.repo.Create(ctx, user)
}

Benefits:

• Each file < 200 lines

• Clear separation of concerns

• Easy to test (no global state)

• Easy to find code

• Easy to onboard new developers

---

Your Challenge

Refactor a messy codebase:

// Start with this messy code in main.go:
package main

import (
    "database/sql"
    "encoding/json"
    "net/http"
)

var db *sql.DB

func main() {
    db, _ = sql.Open("postgres", "...")
    http.HandleFunc("/users", handleUsers)
    http.ListenAndServe(":8080", nil)
}

func handleUsers(w http.ResponseWriter, r *http.Request) {
    if r.Method == "GET" {
        rows, _ := db.Query("SELECT * FROM users")
        // 50 more lines...
    } else if r.Method == "POST" {
        // 50 more lines...
    }
}

// Refactor into:
// - cmd/server/main.go
// - internal/user/handler.go
// - internal/user/service.go
// - internal/user/repository.go
// - internal/user/model.go

---

Key Takeaways

1. Standard layout: Use cmd/, internal/, pkg/ structure

2. Organize by feature: Not by layer (handlers, services, etc.)

3. Small packages: Focused, single responsibility

4. Naming conventions: Short for short scope, descriptive for long scope

5. Use go fmt: Always format before commit

6. Run go vet: Catch common mistakes

7. Accept interfaces: Return concrete types

8. Test with -race: Detect race conditions

---

What I Learned

That 10,000-line main.go refactoring taught me that organization matters:

• 47-line main.go made the project approachable

• Feature-based packages eliminated merge conflicts

• 90% test coverage caught bugs before production

• 3-minute onboarding for new developers

Coming from Python's "flat is better than nested" and JavaScript's "anything goes," Go's conventions felt prescriptive. But after 2 years and 50+ microservices, the consistency across teams has been invaluable.

The time saved navigating organized code? Weeks.

---

Next: Building a Real CLI Tool

In the next article, we'll build a complete CLI tool using cobra and viper. You'll learn the patterns I used to build automation tools that saved hundreds of hours.