What comments are for
A comment is text in your source code that Go ignores completely. It doesn't run, it doesn't print and it doesn't change the program in any way. Comments exist for people: they explain what the code does, or more usefully why it does it, to whoever reads it next. That reader is often you, a few weeks later.
Comments are also a quick way to switch a line off while you experiment. Turn a statement into a comment and Go skips it. Remove the comment marker and the statement is back.
Syntax and examples
Single-line comments with //
Everything from // to the end of the line is a comment:
// Next line will greet the user:
fmt.Println("Hello user!")
Only the second line produces output:
Hello user!
A comment can also share a line with code, after the statement:
fmt.Println("My name is Andy") // prints the first line of the story
Multi-line comments with /* */
Text between /* and */ is a comment, however many lines it covers:
/* This is a
multi-line comment */
fmt.Println("Hello user!")
Most Go code uses //, even for several lines in a row, and keeps /* */ for rare cases like disabling a block of code.
Commenting out code
To keep a line in the file without running it, put // in front of it:
fmt.Println("This runs")
// fmt.Println("This does not run")
This runs
Comments before declarations
A comment placed directly above a function or other top-level declaration is the Go convention for documenting it. Tools show these notes to people who use your code, and by convention the comment starts with the name it describes:
// add returns the sum of a and b.
func add(a int, b int) int {
return a + b
}
Because the compiler ignores comments, they add nothing to what the program does at run time. You can write as many as you need without slowing the program down or changing its output. The real cost is in reading them, so keep each one short and useful: a good comment answers a question the code itself can't, such as why a number was chosen or what a tricky step is working around.
Common mistakes and gotchas
- Using
fmt.Printlnto leave a note.fmt.Println("Story of Andy")prints the text. A comment must start with//so that Go skips it. - A comment marker inside a string is not a comment.
fmt.Println("see http://x // not a comment")prints the whole text, because the//is inside the quotes. - Multi-line comments don't nest. The first
*/ends the comment, even if another/*was opened inside it. After/* outer /* inner */the comment is closed, and anything following it is code again. - Forgetting to close
/*. Without a matching*/, the rest of the file is swallowed into the comment, and the compiler reports an error. - Comments that repeat the code.
// print helloabovefmt.Println("hello")adds nothing. Explain the reason, the unusual choice or the goal. - Old comments. A comment that no longer matches the code is worse than none. Update it when you change the code.
The exercise
The code already contains five fmt.Println lines that tell a short story about Andy. The task is to document it by adding a single-line comment above the first line, with the text Story of Andy.
- Click on the line above the first
fmt.Println, which is the top of the code. - Type
//followed by the text:
// Story of Andy
fmt.Println("My name is Andy")
The comment goes above the first print line, and the print lines below it stay exactly as they were. Don't use fmt.Println for the note, because the point is to print the story and leave the heading out of the output. After the change, the program prints the same lines as before.
Key takeaways
- Comments are notes for humans that Go ignores.
//comments out the rest of the line;/* ... */comments out everything between the markers.- Prefix a statement with
//to disable it without deleting it. - Write comments that explain why, and keep them up to date.