Package scope rules in Go - Deep Dive

Overview - Package scope rules

What is it?

Package scope rules in Go define which variables, functions, types, and constants are accessible within and outside a package. Items declared at package level can be used by all files in the same package. Whether these items are visible outside the package depends on their names: names starting with a capital letter are exported and accessible from other packages, while lowercase names are private to the package.

Why it matters

Without package scope rules, Go programs would have no clear way to organize code and control access to internal details. This would lead to messy codebases where everything is visible everywhere, making maintenance and collaboration difficult. Package scope rules help keep code modular, secure, and easier to understand by controlling what is shared and what stays private.

Where it fits

Before learning package scope rules, you should understand basic Go syntax, variables, functions, and how packages are structured. After mastering package scope, you can learn about interfaces, modules, and advanced package management techniques.

Mental Model

Core Idea

In Go, package scope rules control visibility by using capitalization: capitalized names are public to other packages, lowercase names stay private inside the package.

Think of it like...

Think of a package like a house with rooms. Items with capitalized names are like windows open to the street, visible to everyone outside. Items with lowercase names are like doors inside the house, only accessible to people already inside.

Package Scope Rules
┌─────────────────────────────┐
│        Package (House)       │
│ ┌───────────────┐           │
│ │ Private (door) │  lowercase│
│ │  variables,   │  --------> │ Only inside package
│ │  functions    │           │
│ └───────────────┘           │
│                             │
│ ┌───────────────┐           │
│ │ Exported (window)│ Capitalized│
│ │  variables,   │  --------> │ Visible outside package
│ │  functions    │           │
│ └───────────────┘           │
└─────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding package basics

Concept: Learn what a package is and how Go organizes code into packages.

In Go, a package is a folder containing one or more Go source files. Each file starts with a package declaration like 'package main' or 'package math'. All files in the same folder share the same package name and can use each other's code without import. This grouping helps organize code logically.

Result

You know that all files in the same folder belong to one package and share code internally.

Understanding that a package is a code container helps you see why scope rules matter for organizing and controlling access.

2

Foundation

Package-level declarations

Concept: Variables, functions, types, and constants declared outside functions have package scope.

When you declare a variable, function, type, or constant outside any function, it belongs to the package scope. This means all files in the package can use it. For example: package math var pi = 3.14 func Add(a, b int) int { return a + b } Here, 'pi' and 'Add' are accessible anywhere inside the 'math' package.

Result

You can share data and functions across files in the same package without extra imports.

Knowing package-level declarations lets you organize code into reusable parts within a package.

3

Intermediate

Exported vs unexported names

🤔Before reading on: do you think a variable named 'count' is accessible outside its package? Commit to your answer.

Concept: Capitalization controls visibility: capitalized names are exported (public), lowercase are unexported (private).

In Go, if a name starts with a capital letter, it is exported and visible outside the package. If it starts with a lowercase letter, it is unexported and only visible inside the package. For example: package shapes var Area = 100 // exported var perimeter = 40 // unexported func Perimeter() int { return perimeter } Other packages can use 'Area' and 'Perimeter()', but not 'perimeter' directly.

Result

You can control what parts of your package are public API and what stays private.

Understanding capitalization as the visibility switch is key to controlling access and designing clean APIs.

4

Intermediate

Accessing package members

🤔Before reading on: can you access an unexported function from another package? Commit to your answer.

Concept: Only exported names can be accessed from outside the package using the package name prefix.

When you import a package, you can only use its exported names. For example: import "math" func main() { fmt.Println(math.Pi) // works if Pi is exported fmt.Println(math.pi) // error if pi is unexported } Unexported names are invisible outside their package, so you cannot call or use them directly.

Result

You learn how to use other packages safely without accessing their internal details.

Knowing how to access only exported members prevents accidental misuse of internal package details.

5

Intermediate

Package scope vs file scope

Concept: Package scope spans all files in the package, unlike file scope which is limited to one file.

Variables declared inside a file but outside functions have package scope, so all files in the package can use them. Variables declared inside functions have local scope and are invisible outside that function. For example: // file1.go package util var shared = 10 func GetShared() int { return shared } // file2.go package util func SetShared(v int) { shared = v } Both files share the 'shared' variable because it has package scope.

Result

You understand how package scope allows sharing data across files in the same package.

Distinguishing package scope from file and local scope helps avoid confusion about variable visibility.

6

Advanced

Scope and initialization order

🤔Before reading on: do you think package-level variables are initialized in the order they appear in the code? Commit to your answer.

Concept: Package-level variables are initialized in dependency order before main runs, which can affect program behavior.

Go initializes package-level variables before the program starts running main(). The order depends on dependencies between variables, not just their order in code. For example: var a = b + 1 var b = 2 Here, 'b' is initialized before 'a' because 'a' depends on 'b'. This ensures correct values but can cause subtle bugs if you rely on initialization order incorrectly.

Result

You learn to write safer initialization code and avoid surprises with package variables.

Understanding initialization order prevents bugs caused by using uninitialized or zero-value variables.

7

Expert

Unexported types and embedding tricks

🤔Before reading on: can you embed an unexported type from another package in your exported type? Commit to your answer.

Concept: Unexported types cannot be used directly outside their package, but embedding them inside exported types can expose or hide behavior cleverly.

In Go, you cannot use unexported types from other packages directly. However, you can embed an unexported type inside an exported struct within the same package to control what is exposed. For example: package secret type hidden struct { data int } // Exported type embedding unexported type Public struct { hidden } func NewPublic() Public { return Public{hidden{42}} } Outside packages can use Public but cannot access hidden directly. This pattern helps encapsulate implementation details while exposing needed functionality.

Result

You gain advanced control over package API design and encapsulation.

Knowing how to use unexported types with embedding unlocks powerful encapsulation patterns in Go.

Under the Hood

Go's compiler and linker enforce package scope rules by checking the first character of identifiers. Capitalized names are marked as exported symbols in the compiled package, making them accessible to other packages during linking. Lowercase names are kept internal and not exposed in the package's symbol table. At runtime, this controls what code and data other packages can reference.

Why designed this way?

Go uses capitalization for export because it is simple, readable, and avoids extra keywords or annotations. This design choice keeps the language minimal and easy to learn. Other languages use keywords like 'public' or 'private', but Go's approach reduces clutter and enforces a clear visual distinction. It also fits Go's philosophy of simplicity and explicitness.

Package Scope Enforcement
┌─────────────────────────────┐
│ Source Code Parsing          │
│ ┌─────────────────────────┐ │
│ │ Identifier Names         │ │
│ │ - Capitalized → Exported │ │
│ │ - Lowercase → Unexported │ │
│ └─────────────────────────┘ │
│             ↓               │
│ Compiler Symbol Table       │
│ ┌─────────────────────────┐ │
│ │ Exported Symbols         │ │
│ │ Unexported Symbols       │ │
│ └─────────────────────────┘ │
│             ↓               │
│ Linker & Runtime Access     │
│ ┌─────────────────────────┐ │
│ │ Other Packages Access    │ │
│ │ Only Exported Symbols    │ │
│ └─────────────────────────┘ │
└─────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does a lowercase variable in a package mean it is invisible to all files in the same package? Commit to yes or no.

Common Belief: Lowercase variables are private to the file they are declared in.

Reality: Lowercase variables declared at package level are accessible to all files in the same package, not just one file.

Why it matters: Thinking lowercase means file-private causes confusion and bugs when code in other files cannot access needed variables.

Quick: Can you access an unexported function from another package by importing it? Commit to yes or no.

Common Belief: Importing a package gives access to all its functions, regardless of name capitalization.

Reality: Only exported (capitalized) functions are accessible from other packages; unexported ones are invisible outside their package.

Why it matters: Assuming all functions are accessible leads to compilation errors and wasted debugging time.

Quick: Does Go allow you to change the visibility of a name by using a keyword like 'public' or 'private'? Commit to yes or no.

Common Belief: Go uses keywords like 'public' and 'private' to control visibility.

Reality: Go does not use visibility keywords; it relies solely on capitalization to determine export status.

Why it matters: Expecting keywords causes confusion and misunderstanding of Go's simple and unique approach.

Quick: Can embedding an unexported type from another package in your exported type expose that unexported type outside? Commit to yes or no.

Common Belief: Embedding an unexported type automatically exposes it outside the package.

Reality: Embedding an unexported type inside an exported type does not expose the unexported type itself, only the exported type is visible.

Why it matters: Misunderstanding embedding can lead to accidental exposure of internal details or API design mistakes.

Expert Zone

1

Exported names must be capitalized exactly; even one lowercase letter at the start makes the name unexported.

2

Package scope applies across all files in the package, even if they are in different directories when using Go modules with replace directives.

3

Initialization order of package variables can cause subtle bugs when variables depend on each other across files.

When NOT to use

Package scope rules are fixed in Go and cannot be changed. However, if you need finer-grained access control, consider using interfaces, or separate packages to isolate code. For very large projects, modules and internal packages provide additional encapsulation beyond package scope.

Production Patterns

In production, Go developers design packages with clear exported APIs using capitalized names and keep helper functions and variables unexported. Internal packages are used to hide implementation details from external users. Embedding unexported types inside exported structs is a common pattern to provide controlled access while hiding internals.

Connections

Object-oriented encapsulation

Package scope rules in Go provide encapsulation similar to private and public access modifiers in object-oriented languages.

Understanding Go's capitalization-based visibility helps grasp how encapsulation can be achieved without explicit keywords.

Unix file permissions

Both control access by simple rules: Go uses capitalization, Unix uses read/write/execute bits.

Recognizing access control as a fundamental concept across domains clarifies why simple, consistent rules are effective.

Human social groups

Package scope is like social groups where some information is shared only within the group, and some is public to outsiders.

Seeing code visibility as social boundaries helps understand why controlling access is important for trust and order.

Common Pitfalls

#1 Trying to access an unexported variable from another package.

Wrong approach:

fmt.Println(math.pi) // error: pi is unexported

Correct approach:

fmt.Println(math.Pi) // works if Pi is exported

Root cause:

Misunderstanding that lowercase names are private to the package and not accessible outside.

#2 Declaring a variable inside a function but expecting package-wide access.

Wrong approach:

func foo() {
var count = 10
}
// Trying to use count outside foo() causes error

Correct approach:

var count = 10 // declared at package level
func foo() {}
// count accessible anywhere in package

Root cause:

Confusing local function scope with package scope.

#3 Assuming capitalization affects only functions, not variables or types.

Wrong approach:

type person struct {} // unexported type
var Person person // unexported variable of unexported type

Correct approach:

type Person struct {} // exported type
var PersonVar Person // exported variable

Root cause:

Not realizing that capitalization controls visibility for all identifiers.

Key Takeaways

Go uses capitalization to control package scope: capitalized names are exported and visible outside the package, lowercase names are private inside the package.

Package scope applies to variables, functions, types, and constants declared outside functions, shared across all files in the package.

Only exported names can be accessed from other packages using the package name prefix.

Understanding package scope helps design clean, modular code with clear public APIs and hidden internals.

Advanced patterns like embedding unexported types inside exported structs enable powerful encapsulation and API control.