Functions & Packages

When multiple parameters share a type, you can list them once at the end. a, b int is shorthand for a int, b int.

Multiple return values

Functions that return two values are a defining pattern in Go. You will see them everywhere:

Average returns a float64 and an error. The caller must handle both:

The if err != nil check is the most common pattern in Go. A function that can fail returns its result alongside an error. If the error is nil, the call succeeded and the first value is safe to use. If it is not nil, something went wrong. We look at errors in depth in chapter 12, but you will write this check from day one.

The second call to Average passes no arguments, so it takes the empty-input path:

The _ (blank identifier) discards the float64 return value. We know there is nothing useful there when an error is returned, so we ignore it. This is a deliberate Go idiom.

Here is the full implementation in mathx/stats.go:

A sentinel error is a package-level variable that callers compare against to identify a specific failure. ErrNoNumbers is one example. Its message is "mathx: no numbers given", which is exactly what the program prints when you pass no arguments.

When the input is valid, Average returns nil as the error. nil on an error means no error.

Named returns

MinMax uses another feature: named return values.

The signature (min, max int) names the return values. Inside the function, min and max are pre-declared variables. Naming them makes the signature self-documenting: a reader knows at a glance which value is the minimum and which is the maximum without reading the function body.

Named returns also allow a bare return with no arguments (sometimes called a "naked return"). This returns the current values of the named variables. We do not use that form here because the explicit return min, max is clearer. Use named returns for the documentation value they add to signatures, but avoid bare returns except in very short functions.

Variadic parameters

Both MinMax and Average accept nums ...int. The ... before a type makes it variadic. This means the function accepts any number of arguments of that type. Inside the function, nums acts as a []int slice. You call a variadic function like this:

Or with no arguments at all:

If you already have a slice and want to spread it into a variadic call, append ... to the variable: mathx.MinMax(mySlice...).

Packages

Every .go file starts with a package declaration. The declaration names the package this file belongs to. Files in the same directory must all declare the same package name.

One directory, one package. That is the rule.

package main is special. It is the entry point of an executable program. A file in package main that contains func main() is where go run and go build start execution. Every other package in this project is a library package that main imports.

The module path and import paths

The module path is declared in go.mod:

To import mathx, you combine the module path with the package's directory:

The import path is always the module path plus the package's directory path. It is not the package name (though they match here, they do not have to). Go uses the directory to find the package, not the package declaration.

After importing, you prefix each exported name with the package name:

Visibility: one rule

Go has no public or private keywords. Visibility is controlled by a single rule: an identifier that starts with a capital letter is exported, and one that starts with a lowercase letter is unexported (package-private).

That is the entire rule.

MinMax, Average, and ErrNoNumbers in mathx start with capitals, so main can call them. The helpers smaller and larger start with lowercase letters, so they are invisible outside mathx. Attempting to call mathx.smaller from main.go is a compile error.

The same applies in textx. Label is exported; squeeze is not:

Label calls squeeze freely because they live in the same package. From outside textx, squeeze does not exist.

This rule applies to everything in Go: functions, variables, types, struct fields, and constants. Capital means exported, and lowercase means package-private.

The standard library and a third-party dependency

mathx/stats.go imports only "errors" from the standard library. textx/format.go imports "strings" (also standard) plus two packages from golang.org/x/text:

golang.org/x/text is an extended standard library package maintained by the Go team but not bundled with the language. We added it with go get:

Running those commands added a require line to go.mod and created go.sum:

go.sum holds cryptographic checksums for each downloaded module, so Go can verify the download is authentic and has not been tampered with. Both files belong in version control. You never edit them by hand.

strings.Title used to be the idiomatic way to title-case a string, but it was deprecated in Go 1.18 because it does not handle non-ASCII characters correctly. golang.org/x/text/cases is the maintained replacement:

Label chains three transformations: trim outer whitespace, collapse inner whitespace runs into a single space (via squeeze), then title-case the result. The input " go backend service " comes out as "Go Backend Service".

Running the program

Output:

Every line matches exactly what the code produces. The error line for the empty Average() call shows the sentinel error message from ErrNoNumbers. The Label output shows the full transformation from messy whitespace to clean title case.

What's Next

Next up is control flow: if, for, and switch. The if err != nil pattern you met here shows up everywhere in chapter 8, where writing it starts to feel like second nature.