Comments

Compilers and interpreters usually ignore comments in computer programs. However, humans can understand code more easily if it contains comments because they provide information about each part of the program, explaining what it does. Comments can also serve as a reminder or a note to yourself, which can be very useful in large projects you work on for a long time.

We should write comments during the coding process; otherwise, we could forget to comment on the code after we finish the program. Besides, comments written later may prove less useful in the long run.

Line comment

The line comment in Go begins with two forward slashes // and continues to the end of the line. After the set of forward slashes, it is idiomatic to leave one blank space.

Line comments can appear in two ways: one-line or multiline comments. It's good practice to split a one-line comment into multiline when you think your comment is rather long and hard to read. You can also use multiline comments (or the block comments we'll cover in the next section) to express a complex idea.

An example of line comments looks like this:

// One-line comment


// Multiline comments
//               ▀▀█                        
//   ▄▄▄   ▄▄▄     █     ▄▄▄   ▄ ▄▄    ▄▄▄▄
// █▀ ▀█  █▀ ▀█    █    ▀   █  █▀  █  █▀ ▀█
// █   █  █   █    █    ▄▀▀▀█  █   █  █   █
// ▀█▄▀█  ▀█▄█▀    ▀▄▄  ▀▄▄▀█  █   █  ▀█▄▀█
// ▄  █                               ▄  █
// ▀▀                                 ▀▀ 
//

For documenting the "Hello, World!" program, a multiline comment may look like this:

// Print "Hello, World!"
// to the console
fmt.Println("Hello, World!")

It is best to indent a comment by the same amount as the code it gives information about. A comment following a function definition with no indent would have no indent, and so on. In any case, the comment would be aligned with the code it is commenting on.

Let's take a look at the main function, with comments following each level of indentation in the code:

// main function, no indent, so its comments are not indented either
func main() {
    // 
    // The code in the body of the main function has one level of indentation,
    // therefore, this comment is also indented by one level
    //

    // ...
    var fruit string
    // ...
}

The comment section is generally intended to help programmers, whether the original programmer or a collaborator. A piece of code that looks very long and has many comments is still better than code with no comments because undocumented code is hard to understand and maintain.

When examining the code, you (or anyone else) should be able to understand what happened there or how to do things by looking at the comments.

Block comments

You can create a block comment using an opening tag /* and a closing tag */.

/*
This is a typical block comment
*/


/*
< this is also a block comment >
---------------------------------- 
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
               ||----w |
               ||     ||
*/

We use block comments mostly for documenting packages; pay attention that it is the norm mentioned in Go's official documentation.

/*
Package hello provides a simple function HelloWorld() 
that returns a greeting: "Hello World!"
*/
package hello

func HelloWorld() string {
    return "Hello, World!"
}

As you know, any code in a block comment will not be executed. So, if you want to disable a part of your code temporarily, you can place it in a comment section for a while.

func functionThatWillCrash() error { panic("Our program just crashed!") }

// A normal comment
func greeting() {
    fmt.Println("Hello world")
}

func main() {
    /*
    functionThatWillCrash()
    */

    greeting() // This will execute the greeting function
}

Compiler directives

When you dive deep into the Go toolchain, you'll come across special directives targeted at the compiler. These directives look like usual comments, except for one feature — they usually don't have a space between the slash and the text after it:

//go:build linux && 386

//go:generate goyacc -o gopher.go -p parser gopher.y

//go:noinline
func Foo() {}

For now, you don't need to know what such directives do; we'll get familiar with them a little bit later. If you see such unusual comments in the code, don't remove them; they are there for a purpose.

Conclusion

This topic has tried to convince you that comments are a great way of making your Go programs more readable for humans, including yourself, in the future. Adding appropriate comments can increase the clarity of your code and help others collaborate with you on programming projects. Remember to treat others like you'd like to be treated, and leave useful comments on your code!