Chapter 5: Go Comments
Go Comments.
Comments in Go are super straightforward compared to many languages — no fancy Javadoc tags or weird annotations required for basic use. But Go has two kinds of comments, and one of them (doc comments) is very special because it’s how official documentation (like on pkg.go.dev) gets generated automatically.
I’ll explain everything like your personal teacher: why comments matter in Go, the exact syntax rules (from the official spec), how to use them day-to-day, doc comment best practices (2026 style), and tons of real examples you can copy-paste.
1. Why Comments Are Especially Important in Go
- Go code is designed to be very readable — but sometimes you still need to explain why (not just what).
- No classes/inheritance → less “self-documenting” magic → good comments fill the gap.
- godoc / pkg.go.dev / VS Code hover → pulls comments automatically → your comments = public API docs!
- Community rule: Exported things (Capitalized names) must have doc comments — reviewers will flag you if missing.
- Go team pushes “comment sentences” — full sentences starting with the name.
2. Two Types of Comments (Official Syntax — Go Spec Rules)
From https://go.dev/ref/spec#Comments (still the same in Go 1.26):
| Type | Syntax | Can span lines? | Common use case | Treated as in code |
|---|---|---|---|---|
| Line comment | // anything until end-of-line | No | Everyday explanations, doc comments | Like a newline |
| General (block) comment | /* anything until first */ | Yes | Temporarily disable code, license headers, rare inline | Like a space (if no newline) or newline (if has newline) |
Important rules:
- Comments cannot appear inside strings, runes, or other comments.
- No nesting (/* inside /* doesn’t work).
- // is way more common — block comments are rare except for big disables or package-level blocks.
3. Everyday Examples (Ordinary Comments — Not Doc Comments)
|
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
package main import "fmt" // This is a single-line comment — most common style // You can put them anywhere: above, beside, or even at end of line func main() { // Inline comment at end of line name := "Webliance" // short name for demo /* This is a block comment — can span multiple lines like this. Useful for long explanations or temporarily commenting out code blocks. */ fmt.Printf("Hello %s from Hyderabad! 🇮🇳\n", name) // end-of-line comment } |
Best practice tip: Always put a space after // → // Hello (not //Hello) — it’s idiomatic and gofmt likes it.
4. Doc Comments — The Magic Part (Official Documentation Style)
These are just regular // comments placed immediately before a declaration (no blank line in between).
They get extracted by:
- go doc
- pkg.go.dev
- godoc (old tool)
- VS Code / GoLand hover tooltips
Rules from https://go.dev/doc/comment (2026 current):
- Start with the name being documented (full sentence).
- End with period.
- Use simple Markdown-like syntax (since Go 1.19+ gofmt converts some things):
- Paragraphs (blank lines separate)
- Headings: # Heading (preferred now)
- Links: [net/http](https://pkg.go.dev/net/http)
- Lists: – Item or * Item
- Code:
`go - Preformatted: indent with spaces/tabs
- Exported (CapitalName) → required
- Unexported (lowercase) → optional, but good for team
Example — Package comment (put in one file only, usually doc.go or main file):
|
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
/* Package greeting provides simple greeting functions for learners in Hyderabad. It demonstrates basic Go concepts like functions, strings, and doc comments. Use it as a starting point for your own packages! Example usage: greeting := Hello("Webliance") fmt.Println(greeting) // Output: Hello, Webliance from Telangana! */ package greeting |
Example — Exported function doc comment:
|
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
// Hello returns a friendly greeting message personalized with the given name. // It always appends "from Hyderabad!" for local pride. 🇮🇳 // // If name is empty, it returns a generic greeting. // // Special cases: // - Names longer than 50 characters are truncated with "...". // // Hello is safe for concurrent use. func Hello(name string) string { if name == "" { return "Hello, stranger from Hyderabad!" } if len(name) > 50 { name = name[:47] + "..." } return "Hello, " + name + " from Hyderabad!" } |
→ On pkg.go.dev this looks beautiful: heading, paragraphs, list, code-like special cases.
Example — Type / Struct doc:
|
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
// Config holds server configuration options. // The zero value is ready to use with safe defaults. // // Fields are documented individually for clarity. // Concurrency: Config is not safe for concurrent writes. type Config struct { // Port is the TCP port to listen on. // Default: 8080 Port int // Debug enables verbose logging. // Default: false Debug bool } |
Example — Constant group:
|
0 1 2 3 4 5 6 7 8 9 10 11 12 |
// Status codes returned by the API. // // See also [http.StatusOK] for standard HTTP codes. const ( StatusOK = 200 // Success StatusError = 500 // Internal server error ) |
5. Special Comment Directives (Compiler / Tool Stuff)
These start with //go: (no space!)
Examples (advanced, but good to know):
|
0 1 2 3 4 5 6 7 8 9 10 |
//go:build linux && amd64 // build constraint //go:generate stringer -type=Color // run code generator //line customfile.go:42 // fake source position for errors |
6. Best Practices Summary (2025–2026 Go Community Style)
- Use // for almost everything — block /* */ only when disabling big chunks.
- Doc comments: full sentences, start with name, period at end.
- Exported = must have doc comment.
- Use # Heading, lists, links — gofmt will help format.
- Explain why + special cases + concurrency safety + zero value behavior.
- Avoid: implementation details (how), focus on usage (what/why).
- Tools like go vet, staticcheck, revive sometimes check comment quality.
- For deprecations: // Deprecated: use NewBetterFunc instead. Will be removed in v2.
Your Quick Practice Exercise
Write a small function with good doc comment:
|
0 1 2 3 4 5 6 7 8 9 10 11 12 13 |
// AddNumbers returns the sum of two integers. // It handles overflow by wrapping around (like uint, but on int). // // Example: // result := AddNumbers(5, 3) // returns 8 func AddNumbers(a, b int) int { return a + b } |
Run go doc . AddNumbers in terminal — see your beautiful doc!
Any part confusing?
- Want more on godoc formatting tricks?
- How to write great package overviews?
- Difference between // vs /* in practice?
- Or jump to structs/methods next?
Just say — we’re building your Go foundation step by step! 💪 Keep it up, you’re doing awesome! 🚀🇮🇳
