Packages, visibility and project layout

Why split code into packages?

A 3,000-line main.go is hard to read, test and share. Packages group related code: everything about invoices in one package, everything about the database in another. Each package has a clear job and a small public surface (the names other packages can use).

One folder, one package

• All .go files in one folder must have the same package name (test files may also use name_test).
• The package name is usually the last part of the folder path: folder internal/invoice has package invoice.
• Package names are short, lowercase, one word, no underscores: invoice, store, httpapi. Avoid vague names like util, common or helpers.
• You import a package by its full path: the module path plus the folder, for example "example.com/billing/internal/invoice".

billing/
├── go.mod                 module example.com/billing
├── main.go                package main
└── internal/
    └── invoice/
        ├── invoice.go     package invoice
        └── invoice_test.go

// internal/invoice/invoice.go
package invoice

// GSTPercent is exported: other packages can read it.
const GSTPercent = 18

// Total is exported. It returns the amount with GST, in paise.
func Total(paise int64) int64 {
	return paise + gst(paise)
}

// gst is unexported: only code in package invoice can call it.
func gst(paise int64) int64 {
	return paise * GSTPercent / 100
}

// main.go
package main

import (
	"fmt"

	"example.com/billing/internal/invoice"
)

func main() {
	fmt.Println(invoice.Total(10000)) // 11800
	// invoice.gst(100) // compile error: gst not exported
}

Visibility: just the first letter

Go has no public, private or protected keywords. An identifier (a name of a type, function, variable, constant, field or method) that starts with an upper-case letter is exported. Anything else is visible only inside its own package. The same rule applies to struct fields, which matters for JSON (module 7).

internal/: a wall the compiler enforces

Code inside a folder named internal can only be imported by packages rooted at the parent of internal. In billing/internal/invoice, only packages under billing/ can import it. Other modules cannot, even if your repository is public. Use internal/ for everything you do not want others to depend on.

A sensible layout, without over-engineering

Other rules worth knowing

• Import cycles are not allowed: if package a imports b, then b cannot import a. Fix it by moving the shared piece into a third package or by using an interface.
• func init() runs automatically before main, after package-level variables are set. Keep init small; hidden start-up work is hard to test.
• A blank import, import _ "github.com/jackc/pgx/v5/stdlib", runs a package's init only. Database drivers use this to register themselves (module 8).
• You can rename an import: import ex "example.com/billing/internal/invoice". Use it only to fix name clashes.