Go Comments – Write Clear, Readable, and Documented Go Code

Introduction – Why Comments Matter in Go

Comments are essential for writing readable, maintainable, and documented code. While Go emphasizes simplicity and self-documenting syntax, comments still play a key role in explaining the “why” behind your code decisions.

In this section, you’ll learn:

• How to write single-line and multi-line comments in Go
• Best practices for using comments effectively
• How Go uses comments in tools like godoc
• What not to do when commenting your code

Types of Comments in Go

Go supports two comment styles, both borrowed from C/C++:

Single-line Comment

Begins with //. Everything after // on that line is ignored by the compiler.

// This is a single-line comment
fmt.Println("Hello, Go!")

Use this for brief explanations, annotations, or temporary code disabling.

Multi-line Comment (Block Comment)

Enclosed between /* and */. Useful for longer or multi-line commentary.

/*
This is a multi-line comment.
It spans multiple lines and is ignored by the compiler.
*/
fmt.Println("Welcome to Golang")

Note: Multi-line comments cannot be nested in Go.

Commenting for Documentation

Go has a powerful documentation tool called godoc which generates docs from your code comments. To make use of it:

• Add doc comments just above functions, types, variables, or constants
• Begin with the name of the item being described

Example:

// Greet prints a greeting message to the user.
func Greet(name string) {
    fmt.Printf("Hello, %s!\n", name)
}

When you run:

godoc -http=:6060

You can view your documentation in a browser at http://localhost:6060

Best Practices for Comments in Go

Do:

• Use comments to explain why something is done, not what (the code already shows that).
• Document public functions and types using doc comments.
• Keep comments up to date as the code changes.

Avoid:

• Writing obvious comments: i := 0 // Set i to 0 ← Redundant
• Leaving old, misleading comments in code
• Over-commenting — clarity should come from clean code

Example – Combining All Comment Types

package main

import "fmt"

// main is the entry point of the application
func main() {
    /* Display a message to the user.
       This is an example of a multi-line comment. */
    fmt.Println("Comment examples in Go!")
}

Output:

Comment examples in Go!

Summary – Recap & Next Steps

Go makes commenting simple and powerful, especially when combined with tools like godoc. Well-placed comments improve code clarity and serve as in-code documentation.

Key Takeaways:

• Use // for single-line and /* */ for multi-line comments
• Avoid redundant comments; explain intent, not syntax
• godoc uses comments to generate rich documentation
• Comments should evolve along with your codebase

Next: Learn about Go’s Fmt Package and how to format data in output.

FAQs – Go Comments

Can Go comments be nested?
No. Multi-line comments (/* ... */) cannot be nested in Go.

What is the godoc tool used for?
It generates documentation from Go source code, using comments written above declarations.

Are comments compiled into the binary?
No. Comments are stripped out during compilation and have no effect on the executable.

Should I comment every line of Go code?
No. Only comment code that isn’t self-explanatory or needs clarification for future maintainers.

Can I use comments to temporarily disable code?
Yes. Use // or block comments to comment out lines of code during debugging or testing.