Go — Comments

Single-line comments

Use // for a single-line comment:

package main

import "fmt"

func main() {
    // This is a comment
    x := 10 // inline comment
    fmt.Println(x)
}

Multi-line comments

Use /* ... */ for multi-line comments:

package main

import "fmt"

func main() {
    /*
      This is a multi-line comment.
      It can span multiple lines.
      Useful for longer explanations.
    */
    fmt.Println("Hello")
}

Doc comments

Go uses doc comments for API documentation. Place them directly above the declaration:

// Add returns the sum of two integers.
func Add(a, b int) int {
    return a + b
}

// Person represents a human being.
//
// A Person has a name and an age.
// Use NewPerson to create a new instance.
type Person struct {
    Name string
    Age  int
}

// NewPerson creates a new Person with the given name and age.
func NewPerson(name string, age int) *Person {
    return &Person{Name: name, Age: age}
}

Package documentation

Document the package with a comment at the top of any file:

// Package mathutils provides mathematical utility functions.
//
// It includes basic arithmetic operations, statistical functions,
// and helper methods for common calculations.
package mathutils

// Add returns the sum of two integers.
func Add(a, b int) int {
    return a + b
}

Example functions

Go's test framework supports example functions:

// ExampleAdd demonstrates the Add function.
func ExampleAdd() {
    result := Add(2, 3)
    fmt.Println(result)
    // Output: 5
}

// ExampleNewPerson demonstrates creating a new Person.
func ExampleNewPerson() {
    p := NewPerson("Alice", 30)
    fmt.Println(p.Name)
    // Output: Alice
}

When to comment

• Explain why something is done
• Document public APIs with doc comments
• Mark TODOs and FIXMEs
• Don't comment obvious code

// GOOD: Explain WHY
// Retry with exponential backoff because the API may be temporarily unavailable
for i := 0; i < maxRetries; i++ {
    time.Sleep(time.Duration(1<<i) * time.Second)
}

// BAD: Redundant comment
x := 10 // Set x to 10

go doc

Generate documentation from comments:

# View package documentation
go doc fmt

# View specific function
go doc fmt.Println

# View all documentation
go doc -all

Mini Practice

Write Go code that:

1. Uses // comments to explain variable declarations
2. Uses /* */ for a multi-line description
3. Writes doc comments for a function and type
4. Creates an example function for testing

Up Next

In the next lesson, you'll learn about Variables — declaring and using variables in Go.