Go Formatting

Introduction

Consistent code formatting is essential for writing maintainable, professional Go applications. Unlike many programming languages where formatting is often a matter of personal preference or team standards, Go takes a unique approach: it provides official tools that automatically format your code according to standard conventions.

This approach has several benefits:

• Eliminates debates about formatting styles
• Makes all Go code look familiar regardless of who wrote it
• Improves readability and maintainability
• Simplifies code reviews by focusing on substance rather than style

In this guide, we'll explore Go's formatting tools, conventions, and best practices to help you write clean, professional Go code from day one.

The Go Formatting Philosophy

The Go language creators believe that a canonical format allows programmers to focus on meaningful aspects of the code rather than spending time and energy on formatting decisions. As the Go proverb states:

Gofmt's style is no one's favorite, yet gofmt is everyone's favorite.

This means that while no one would have personally chosen every formatting rule exactly as implemented, the consistency and automation provided by the standard formatter are more valuable than personal preferences.

Formatting Tools in Go

gofmt

gofmt (pronounced "go format") is the original Go formatting tool that comes with the Go installation. It automatically formats Go source code according to Go's standard style.

Basic Usage

go

// Command to format a file in-place
gofmt -w file.go

// Command to format all Go files in a directory
gofmt -w .

When you run gofmt without the -w flag, it prints the formatted code to standard output without modifying files.

go fmt

go fmt is a convenient wrapper around gofmt that works with Go packages. It's often easier to use than direct gofmt commands.

Basic Usage

go

// Format the current package
go fmt

// Format a specific package
go fmt github.com/username/project

// Format all packages in the current directory and subdirectories
go fmt ./...

IDE Integration

Most Go-friendly IDEs and text editors include built-in support for Go formatting:

• VS Code with Go extension: Auto-formats on save
• GoLand: Auto-formats on save
• Vim with vim-go plugin: Formats code with :GoFmt
• Emacs with go-mode: Formats on save or with specific commands

This integration makes it very easy to maintain properly formatted code without extra effort.

Key Formatting Rules

Let's look at some of the most important Go formatting conventions:

1. Indentation with Tabs

Go uses tabs, not spaces, for indentation:

go

func Example() {
	// This line is indented with a tab, not spaces
	fmt.Println("Hello, World!")
	if true {
		// Nested indentations use additional tabs
		fmt.Println("Nested code")
	}
}

2. Line Length

Go doesn't enforce a strict line length limit, but idiomatic Go code typically avoids very long lines. The formatter doesn't automatically wrap long lines - that's left to the programmer's discretion.

3. Braces Placement

Go requires opening braces to be on the same line as their controlling statement:

go

// Correct
if x > 0 {
	// Do something
}

// Incorrect - will not compile
if x > 0
{
	// Do something
}

4. Spacing

Go has specific rules for spaces around operators and in various contexts:

go

// Binary operators have spaces on both sides
x = y + z

// No space after unary operators
x = -y

// No space in function calls
fmt.Println("Hello")

// No space in array/slice indices
arr[0] = 1

5. Import Organization

Imports are automatically grouped and alphabetized within each group:

go

import (
	"fmt"     // Standard library imports first
	"strings" // Alphabetically ordered
	
	"github.com/example/package" // Third-party packages next
	
	"mycompany.com/myproject/mypackage" // Local packages last
)

Practical Example

Let's look at a complete example of poorly formatted Go code and how gofmt transforms it:

Before Formatting

go

package main
import(
"fmt"
"strings"
)

func main(){
x:=10
  y:= 20
	result:= complexCalculation( x,y )
fmt.Println("The result is",result)
}

func complexCalculation(a,b int)int{
  // This function does a complex calculation
if a>b{return a*b
}else{
return a+b
}
}

After Formatting

go

package main

import (
	"fmt"
	"strings"
)

func main() {
	x := 10
	y := 20
	result := complexCalculation(x, y)
	fmt.Println("The result is", result)
}

func complexCalculation(a, b int) int {
	// This function does a complex calculation
	if a > b {
		return a * b
	} else {
		return a + b
	}
}

The formatter has:

1. Added proper spacing around operators
2. Reorganized imports
3. Added missing spaces after colons in short variable declarations
4. Fixed indentation
5. Added proper spacing in function calls
6. Fixed brace placement and block indentation

Real-World Application: Pre-Commit Hooks

In professional Go projects, it's common to enforce formatting standards using Git pre-commit hooks. Here's a simple example:

bash

#!/bin/sh
# Pre-commit hook to ensure all Go files are properly formatted

# Get all staged Go files
GO_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.go$')

if [ -n "$GO_FILES" ]; then
  # Format all staged Go files and stage the changes
  echo "Formatting Go files..."
  echo "$GO_FILES" | xargs gofmt -w
  echo "$GO_FILES" | xargs git add
fi

exit 0

With this hook, all Go files will be automatically formatted before each commit.

Additional Formatting Tools

Beyond the standard formatting, several tools extend Go's code quality checks:

golint

golint checks for style mistakes beyond simple formatting:

bash

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

go vet

go vet analyzes code for suspicious constructs that might indicate bugs:

bash

go vet ./...

Summary

Go's approach to code formatting is refreshingly simple: the language provides standard tools that automatically format your code according to agreed-upon conventions. This allows Go programmers to focus on writing good code rather than debating formatting styles.

Key takeaways:

• Use gofmt or go fmt to automatically format your code
• Configure your editor to run formatting on save
• Follow Go's standard formatting conventions
• Use Git hooks to ensure all committed code is properly formatted
• Remember that consistent formatting improves code readability and maintainability

Exercises

1. Take a poorly formatted Go file and run gofmt on it. Compare the before and after.
2. Configure your IDE or editor to automatically format Go files when saving.
3. Create a simple Git pre-commit hook that runs go fmt before each commit.
4. Take a well-formatted Go file and deliberately introduce formatting errors. Try to identify them without running gofmt.

Additional Resources

• Effective Go - Formatting
• Go Code Review Comments
• How to Write Go Code
• Go Proverbs