Forem: jjpinto

Go Naming Conventions Cheat Sheet: Idiomatic Patterns for Clean Code

jjpinto — Sat, 12 Jul 2025 11:01:21 +0000

🧩 Part 2 of the Idiomatic Go Series — see Part 1: The Power of Idiomatic Go

Naming in Go isn’t just about style — it’s about writing idiomatic code that’s clear, predictable, and Go-like. This cheat sheet lays out key naming conventions for variables, types, interfaces, and packages, so you can avoid common pitfalls and write cleaner code with confidence. Whether you’re new to Go or refining your best practices, this guide has you covered.

📌 Context and Cancellation

Go’s concurrency model relies on context, and clear naming keeps things tight.

Purpose	Idiomatic Name
Context variable	`ctx`
Cancel function	`cancel`

Example:

// Use 'ctx' and 'cancel' for clarity
ctx, cancel := context.WithTimeout(context.Background(), time.Second)
defer cancel()

📌 Error Handling

Errors are central to Go—keep their names simple to focus on the logic.

Purpose	Idiomatic Name
Error variable	`err`

Example:

// 'err' as the last return value
result, err := doSomething()
if err != nil {
    return err
}

✅ Tip: Errors are returned as the last return value in Go functions.

📌 Loop Variables

Short names for loops make iteration clean and intuitive.

Purpose	Idiomatic Name
Index in loop	`i`, `j`
Value in loop	`v`, `val`
Key in a map	`k`, `key`

Example:

// 'i' and 'v' for index and value
for i, v := range items {
    fmt.Println(i, v)
}

📌 Receivers

Receiver names should be concise and tied to the type.

Type Name	Receiver Name
`User`	`u`
`Server`	`s`
`Client`	`c`

Example:

// Short 'u' for User type
func (u *User) FullName() string {
    return u.First + " " + u.Last
}

🧠 Note: Use 1-letter lowercase receivers for brevity and clarity.

📌 Constants

Constants in Go follow camelCase for unexported names and UpperCamelCase for exported ones.

Purpose	Idiomatic Name
Exported constant	MaxRetries
Unexported constant	maxBufferSize

Example:

const MaxRetries = 3
const defaultTimeout = 30 * time.Second

✅ Tip: Use descriptive names for constants to reflect their purpose, and avoid single-letter names like c or k.

📌 Package Naming

Package names should be short, lowercase, and descriptive, avoiding stuttering (e.g., don’t name a package userutils if it’s for User types).

Purpose	Idiomatic Name
Package name	log, http, user

Example:

import "github.com/example/user"

✅ Tip: Keep package names singular (e.g., user not users) and avoid generic terms like utils.

📌 Common Short Names

These shorthand names are standard across Go projects.

Meaning	Name
Temporary value	`tmp`
Buffer	`buf`
Configuration	`cfg`
Request	`req`
Response	`resp`
Logger	`log`, `logger`

📌 Boolean Naming

Booleans should read naturally in if statements.

Purpose	Idiomatic Name
Flag for readiness	`isReady`
Permission check	`hasPermission`
Retry condition	`shouldRetry`

Example:

// Clear names for boolean logic
if isReady && hasPermission {
    doSomething()
}

✅ Tip: Name booleans to imply their truthy state.

🧵 Wrapping Up

Naming conventions are a subtle but powerful part of idiomatic Go. These short, predictable patterns make your code easier to read, review, and maintain — especially when working across teams.

This cheat sheet gives you the patterns to make your code feel like it belongs in the Go ecosystem.

💬 Got a favorite Go naming convention or a tricky naming challenge? Share it below—let’s make this cheat sheet even better together!

💡 Curious why idiomatic Go matters?
Start with Part 1: The Power of Idiomatic Go — it’s the foundation for this cheat sheet.

📚 Want to go even deeper? Explore Effective Go and the Go Style Guide — they’re foundational reads for writing Go the idiomatic way.

This post was reviewed with AI assistance to refine clarity and structure

The Power of Idiomatic Go: What Makes It Different from Java and C#

jjpinto — Sat, 12 Jul 2025 10:59:43 +0000

🧩 Part 1 of the Idiomatic Go Series — see Part 2: Go Naming Conventions Cheat Sheet

Idiomatic Go is more than a style — it reflects the language’s simplicity, clarity, and philosophy, especially when contrasted with Java and C#.

📌 TL;DR

Idiomatic Go = clear, consistent, and community-driven code
Java/C# = flexible, but less opinionated
Go’s design and tooling make idioms essential, not optional
Embracing idioms = better teams, better code, better sleep 😄

If you've spent any time in the Go community, you've probably heard the phrase "idiomatic Go" more times than you can count. But have you ever wondered why Go developers emphasize idioms more than those using Java or C#?

As someone who’s worked across multiple languages, I’ve noticed that Go has a unique culture around idioms — and it’s not just a stylistic preference. It’s deeply embedded in both the language's design and its community practices.

🧠 What Is "Idiomatic" Code in Go?

In everyday language, an idiom is a phrase like “kick the bucket” — you can’t figure out its meaning just by looking at the individual words.

In programming, an idiom is a common and recognizable way of writing code that the community understands, expects, and uses. It’s not just about syntax — it’s about style, intent, and best practices.

In Go, writing idiomatic code means aligning with the language’s core values and conventions. You're not just writing code that works — you're writing code that looks and feels like Go.

Here’s what idiomatic Go code usually embodies:

✅ Readable — Easy for other Go developers to scan and understand
✅ Minimalist — Avoids unnecessary abstractions or clever tricks
✅ Pragmatic — Leverages Go’s strengths (like simplicity and concurrency)
✅ Consistent — Follows community standards (naming, structure, error handling)

Idioms in Go act like a shared language — they reduce friction, improve collaboration, and make Go projects feel familiar, even across teams.

🧭 Why Idiomatic Go Matters More Than in Java or C#?

1. Simplicity by Design

Go was built to be small and simple. It avoids features that often lead to complexity (like inheritance or method overloading). That means there are fewer ways to do things — and more agreement on the “right” way.

2. Tooling That Keeps You in Line

Go’s tooling is famously opinionated — and that’s a good thing!

gofmt formats your code automatically. No arguments. No config.
There’s no debate over tabs vs spaces — Go just decides for you!
go vet, golint, and other tools spot non-idiomatic patterns and enforce Go best practices.

3. A Culture of Clarity

The Go community values clarity over cleverness. Rob Pike’s famous Go proverb says:

“Clear is better than clever.”

This mindset encourages patterns that are easy to read, easy to maintain, and easy to teach.

⚖️ How Java and C# Stack Up

Java and C# are powerful, mature languages — but they’re also more flexible and layered. You can write object-oriented, functional, reactive, or procedural code depending on your team or framework.

That flexibility is great, but it also means:

There’s no single “idiomatic” way to do things
Style and structure vary widely between teams
Tooling is less opinionated — you configure everything

In short: Java and C# have idioms, but they’re not as central or enforced as they are in Go.

🌍 Real-World Benefits of Idiomatic Go

So why does this matter?

Because idiomatic Go leads to:

🚀 Faster onboarding — new devs can read and understand code quickly
🔍 Easier code reviews — fewer debates about style or structure
🧼 More maintainable codebases — consistent patterns reduce bugs

It’s not just about aesthetics — it’s about developer velocity and team health.

🧪A Quick Code Comparison

Let’s say you want to launch 100 goroutines and safely append to a shared slice.

✅ Idiomatic Go:

// Idiomatic Go: Safe concurrent writes to a slice
var mu sync.Mutex
var wg sync.WaitGroup
s := []int{}

for i := 0; i < 100; i++ {
    wg.Add(1)
    go func(i int) {
        defer wg.Done()
        mu.Lock()
        defer mu.Unlock()
        s = append(s, i)
    }(i)
}
wg.Wait()

🧩 Java or C#?

You could do this in many ways — ExecutorService, Parallel.For, synchronized, lock, ConcurrentBag, etc. But there’s no single idiomatic pattern that everyone agrees on.

🧵 Final Thoughts

Idiomatic Go isn’t just a quirk — it’s a reflection of the language’s DNA. By keeping the language small and the tooling strict, Go encourages a shared way of writing code that’s easy to read, reason about, and maintain.

That’s why idiomatic Go matters more — and why it’s worth learning and embracing if you’re working in the language.

💡 Ever wonder why 'ctx' beats 'context'?

Or why 'err' trumps 'e'? Or 'pkg' wins over 'packageNameLongerThanLife'?

Naming isn’t just cosmetic—it’s idiomatic.

In Part 2: Go Naming Conventions Cheat Sheet, I break down the tiny naming choices that make a big impact in Go.

🧠 It's not just what you name—it's why you name it that way.

This post was reviewed with AI assistance to refine clarity and structure

Capital Letters Made My Workmate Quit Go—But Should You?

jjpinto — Wed, 18 Jun 2025 12:47:52 +0000

One of Go’s simplest rules—capitalization for visibility—turned my colleague off the language entirely. But is it really that bad? In this article, I explore why this rule exists, why it feels weird, and why it might actually be one of Go’s smartest design choices.

The Moment My Workmate Walked Away

A few weeks ago, I told a workmate I was learning Go. His response?
"Congrats—but I could never deal with a language where capital letters decide everything."

At first, I laughed. Then I realized he wasn’t joking. For him, the idea that a function’s visibility depends on whether it starts with a capital letter was enough to walk away from the language entirely.

It got me thinking: Is this rule really that strange—or are we just not used to simplicity when we see it?

Why Go Uses Capitalization for Visibility

In Go, capitalization isn’t just a style choice—it’s a visibility rule.

If a function, variable, or type starts with a capital letter, it’s exported (public).
If it starts with a lowercase letter, it’s unexported (private to the package).

There’s no public, private, or protected keyword. This minimalist approach aligns with Go’s philosophy: fewer keywords, more clarity. But for developers coming from Java, C#, or Python, this can feel unintuitive—even frustrating—at first glance.

Simplicity Can Feel Complicated

“Simplicity is complicated.” — Rob Pike, Go Proverbs Talk

For many developers—especially those from object-oriented backgrounds—this rule feels like a step backward. We’re used to explicit visibility modifiers: public, private, protected.

But Go takes a radically transparent approach. The rule is simple, consistent, and enforced by the compiler. Once you get used to it, it becomes second nature—and you start to appreciate how much boilerplate it eliminates.

Example: Capitalization and Visibility in Go

package mypackage

// Exported (public)
func SayHello() string {
    return "Hello from SayHello!"
}

// Unexported (private)
func sayGoodbye() string {
    return "Goodbye from sayGoodbye!"
}

In this example:

SayHello is exported (public) because it starts with a capital letter. It can be accessed from other packages.
sayGoodbye is unexported (private) because it starts with a lowercase letter. It can only be used within the same package.

Should One Rule Make You Quit Go?

I don’t think so. Every language has its quirks—Java has checked exceptions, Python has strict indentation, and C# has LINQ syntax. Go’s capitalization rule might seem odd at first, but it’s a small price to pay for a language that offers fast compilation, powerful concurrency, and a clean, consistent developer experience.

If you’re curious about Go, don’t let a capital letter stop you. Dive in—you might just find it’s exactly what you’ve been looking for.

Have you ever struggled with Go's capitalization rule? Does it make the language harder or simpler for you? Let me know in the comments!