What is the role of comments in Go language

The role of comments in the program is to annotate and explain the program, improve the readability of the program code, and facilitate reading of the source code; the purpose is to make it easy for others and yourself to understand, and you will know it at a glance What does this code do. Go's comments are divided into line comments "//" and block comments "/* */"; in actual use, line comments are used more often, and block comments are mainly used to format large sections of code or package comments. use.

The operating environment of this tutorial: Windows 7 system, GO version 1.18, Dell G3 computer.

What is the role of comments

Comments are explanations and explanations of the code, and their purpose is to make it easier for people to understand the code. Comments are when the programmer writes an explanation or hint for a statement, program segment, function, etc., which can improve the readability of the program code.

The role of comments in the program is to annotate and explain the program to facilitate reading of the source code. The compilation system will automatically ignore the commented part when compiling the source code, so the comments will not play any role in realizing the function of the program. Appropriately adding comments to the source code can improve the readability of the source code.

Comments are explanations and descriptions of the code. The purpose is to make it easy for others and yourself to understand, and you can know what this code is used for at a glance. Correct program comments generally include preamble comments and functional comments. The main contents of the preamble comments include the module interface, data description and module functions. The main content of the module's functional comments includes the function of the program segment, the function of the statement and the status of the data.

Classification of go comments

Go comments include line comments // and block comments /* */. In actual use, line comments are used more often, and block comments are mainly used to format large sections of code or package comments.

In goland, the shortcut key for line comments is Ctrl /, and the shortcut key for block comments is Ctrl Shift /

Application

File comments

Add a comment before each file. This comment is used to describe the author, time, and copyright.

We can open a package to view it at will. For example, in the builtin.go package

// Copyright 2011 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

, there is time 2011, author go, and copyright. We can open other files at will. , it can be found that only time is changing, while nothing else changes.

In goland, you can find and modify the file comment template in Settings/Editor/File and Code Templates/Files/Go File, so that comments will be automatically generated every time you create a new file.

This is my template

//@program: ${PROJECT_NAME}
//@author: edte
//@create: ${YEAR}-${MONTH}-${DAY} ${HOUR}:${MINUTE}
package ${GO_PACKAGE_NAME}

Package comments

Package comments are used to describe and introduce the package and provide the package some information.

In go, there is only one package in a directory (excluding subdirectories), so there can be multiple files in a package. Generally, just write a package comment on one of the files.

Similarly, let’s look at the builtin.go file in the builtin package

/*
    Package builtin provides documentation for Go's predeclared identifiers.
    The items documented here are not actually in package builtin
    but their descriptions here allow godoc to present documentation
    for the language's special identifiers.
*/

We can see that the function of the builtin package is to provide documentation for predefined identifiers.

We also look at the errors.go file in the errors package. We can see that the package comments are very long

// Package errors implements functions to manipulate errors.

Here we talk about the package errors that implements some error handling methods Function.

// The New function creates errors whose only content is a text message.
//
// The Unwrap, Is and As functions work on errors that may wrap other errors.

There is a lot later, which talks about files, principles, applications and other information related to the errors package.

If we continue to look at the source code, we will find that the package comments all start with package, a verb . Generally, this short sentence explains the function of the package, and then look at the specific package description. Additional information about the package.

Function comments

Function comments are used to describe the function of the function and other related information.

Let’s also look at the errors.go file in the errros package

// New returns an error that formats as the given text.
// Each call to New returns a distinct error value even if the text is identical.
func New(text string) error {
    return &errorString{text}
}

这里用一句话说明了 New 功能的作用，即返回一个自定义的错误。

然后又用一句话说了这个函数相关的特点，即使文本相同，每次对 New 的调用也会返回一个不同的错误值。

如果同样查看其他源码中的函数，我们发现一般几乎都是 函数名 + 一个动词 的句子开头。这个句子同样说明了这个函数的作用，即函数干了些什么。

而其他需要讲解的信息则以复杂度为基础，如果感觉某个点不容易理解，那么最好都要写注释，如函数签名，函数原理，函数使用过程中需要注意的点等。

数据类型注释

数据类型注释说明 这个数据类型用来干什么。

如 errors.go 中

// errorString is a trivial implementation of error.
type errorString struct {
    s string
}

这里就说明了  errorString 的作用，即 error 的具体实现。

如 built.go 中

// bool is the set of boolean values, true and false.
type bool bool

// true and false are the two untyped boolean values.
const (
    true  = 0 == 0 // Untyped bool.
    false = 0 != 0 // Untyped bool.
)

// The error built-in interface type is the conventional interface for
// representing an error condition, with the nil value representing no error.
type error interface {
    Error() string
}

几乎都是以 类型名 + is 开头的句子，这个句子说明了这个类型的作用。

TODO

TODO 即 to do, 是一个特殊的注释，表明在此处有功能等待编写，

FIXME

FIXME 即 fix me, 也是一个特殊的注释，表明此处的功能需要修正，甚至不能运行

XXX

XXX 也是一个特殊的注释，表明此处的功能实现方法有点问题，需要更改

godoc

godoc 是一个实用的工具，可以根据特定的注释格式生成文档。也可以用来查看文档，同样的 go doc 命令也是相似的作用，具体的可以查看这篇文章。

【相关推荐：Go视频教程、编程教学】

The above is the detailed content of What is the role of comments in Go language. For more information, please follow other related articles on the PHP Chinese website!