Comments in Go
Learn how to write clean, readable, and professional Go code using single-line, multi-line, and documentation (godoc) comments.
Single-line Comments
Single-line comments start with `//` and are best for short explanations, reminders, or clarifying what a specific line does.
1. Basic Single-line Comment
Everything after `//` on that line is ignored by the Go compiler.
2. Inline Comment (End of Line)
Inline comments are placed at the end of a line to explain the line quickly.
3. Debug Notes / TODOs
Common practice: using keywords TODO, FIXME, NOTE so they can be searched easily in VS Code.
Multi-line Comments
Multi-line comments start with `/*` and end with `*/`. They are useful when you want to explain a block of logic or temporarily disable a block of code.
1. Basic Multi-line Comment
Multi-line comments can span across many lines and are great for explaining bigger blocks.
2. Temporarily Disable a Code Block
Useful during debugging when you want to stop some code from running without deleting it.
3. Warning / Big Notes
Many teams use multi-line comments for warnings or important notes.
Documentation Comments (godoc)
In Go, documentation comments are plain comments that appear directly above exported names (capitalized). The tool `go doc` and the Go docs use these comments. The first sentence should be a summary that starts with the name of the thing being documented. This style is called godoc and is the standard way to document Go code.
1. Documenting a Function
Place a comment above the function; the first line should start with the function name and describe what it does. Describe parameters and return values in the following lines.
2. Documenting a Function That Returns a Value and an Error
In Go, functions often return a value and an error. Document both in the comment so callers know how to handle them.
3. Useful godoc Conventions
Following these conventions makes your codebase self-documented and easier to maintain. The `go doc` command and pkg.go.dev use these comments.