Go Comments

Comments in Go explain code, record important decisions, and make programs easier to review and maintain. The Go compiler ignores comment text, so comments do not become part of the executable program.

Go supports two comment forms: line comments beginning with // and block comments enclosed by /* and */. Line comments are commonly used for short explanations and documentation comments, while block comments are useful when a comment spans several lines.

Go Single Line Comments with //

To write single line comments in golang, use double slash at the beginning of the comment // comment. In the following example, we have written single line comments.

example.go

</>
Copy
package main  

import "fmt"  

func main() { 
	// this is a single line comment
	fmt.Println("Hello World")
	// this is another comment
}

A line comment continues from // to the end of the current line. It may appear on its own line or after a Go statement.

</>
Copy
// A comment on its own line
value := 10 // A comment placed after a statement

Comments placed above a statement are generally easier to read than long comments appended to the end of a line. End-of-line comments are best kept short.

Go Multiline Comments with /* and */

To write multi line comments in golang, enclose the comment lines in /* comment(s) */. In the following example, we have written multi line comments.

example.go

</>
Copy
package main  

import "fmt"  

func main() { 
	/*	this is a multi line comment
		this is another line in the same comment
	*/
	fmt.Println("Hello World")
}

A block comment begins at /* and ends at the next */. It can occupy part of one line or extend across multiple lines.

</>
Copy
/* One-line block comment */

/*
A block comment
written on several lines.
*/

Go block comments cannot be nested. A /* sequence inside an existing block comment does not create a separate nested comment; the first following */ closes the comment.

Go Documentation Comments for Packages and Declarations

Documentation comments describe exported packages, constants, variables, functions, methods, and types. Go documentation tools associate a comment with the declaration immediately following it.

A package comment normally starts with Package followed by the package name. A comment for an exported declaration should begin with the name being documented. This convention helps tools such as go doc produce clear documentation.

</>
Copy
// Package convert provides basic unit conversion functions.
package convert

// CelsiusToFahrenheit converts a Celsius temperature to Fahrenheit.
func CelsiusToFahrenheit(celsius float64) float64 {
	return celsius*9/5 + 32
}

// Converter stores configuration used during unit conversion.
type Converter struct {
	Precision int
}

Documentation comments should explain what a declaration does, including behavior that is not obvious from its name or signature. The official Go documentation comments guide describes formatting rules for headings, links, lists, and code blocks in Go documentation.

Using Comments with gofmt and go doc

The gofmt command formats Go source code and normalizes spacing around comments. The go doc command displays documentation comments for packages and declarations.

</>
Copy
gofmt -w example.go
go doc
ngo doc CelsiusToFahrenheit

Run gofmt before committing Go code so comments and declarations follow the standard source layout. Use go doc to confirm that exported declarations produce understandable documentation.

When Go Comments Improve Code Readability

Useful comments provide context that the code cannot communicate clearly by itself. They are especially helpful when explaining:

  • why a particular algorithm or workaround was selected;
  • assumptions that a function depends on;
  • units, ranges, or formats expected by a value;
  • side effects that are not obvious from a function signature;
  • compatibility constraints involving an external API, file format, or Go version.

Avoid comments that merely repeat the code. For example, // Add one to count above count++ does not provide useful information. A better comment explains why the increment occurs at that point in the program.

</>
Copy
// Count the initial request because the retry loop records only later attempts.
count++

Go Comment Conventions and Common Mistakes

  • Keep comments current: update a comment whenever the related code changes.
  • Describe intent rather than syntax: explain why the code exists instead of translating each statement into English.
  • Place documentation directly above its declaration: a blank declaration or unrelated comment between them can make the association unclear.
  • Start exported declaration comments with the declared name: write // ParseDate ... for a function named ParseDate.
  • Do not store secrets in comments: comments committed to source control can expose passwords, tokens, private URLs, or customer data.
  • Do not rely on nested block comments: Go closes a block comment at the first */.

Temporarily Commenting Out Go Code

During debugging, individual lines can be disabled with //. Line comments are often safer than wrapping a large region in /* ... */, especially when that region already contains a block comment.

</>
Copy
func main() {
	fmt.Println("Program started")

	// fmt.Println("Temporary diagnostic message")
	// runExperimentalStep()

	fmt.Println("Program finished")
}

Remove obsolete commented-out code after testing. Version control retains earlier implementations and is usually a better place to recover deleted code.

Frequently Asked Questions about Go Comments

How do you write a comment in Go?

Use // for a comment that continues to the end of the line. Use /* and */ for a block comment that may span multiple lines.

How do you comment multiple lines in Golang?

Place /* before the first line and */ after the last line. You can also add // to each line, which is often preferable when temporarily disabling code.

Can Go block comments be nested?

No. A block comment ends at the first */. Use line comments when the text or code being commented already contains block comments.

What is a documentation comment in Go?

A documentation comment is a comment placed immediately before a package or declaration so tools such as go doc can display it. Comments for exported declarations conventionally begin with the declaration name.

Does the Go compiler include comments in the executable?

No. Comments are ignored as program instructions and are not executed. However, documentation tools and source-analysis tools may read them.

Go Comments Editorial QA Checklist

  • Verify that every /* block has a matching */.
  • Confirm that comments still describe the current behavior of the Go code.
  • Check that comments for exported Go declarations begin with the declaration name.
  • Run gofmt and review the resulting comment placement.
  • Remove secrets, obsolete TODO notes, and unnecessary commented-out code.
  • Use go doc to review package and API documentation as readers will see it.

Go Comments Summary

In this Go Tutorial, we learned how to write single line comments and multiple line comments.

Use // for line comments and most documentation comments. Use /* ... */ when a true block comment is appropriate. Keep comments accurate, explain intent rather than obvious syntax, and follow Go documentation conventions for exported packages and declarations.