What is the comment coding specification of go language?

Comment encoding specifications: 1. All exported objects need to be commented to explain their purpose; non-exported objects need to be commented according to the situation. 2. If the object is countable and the quantity is not clearly specified, always use the singular form and the continuous continuous tense; otherwise, use the plural form. 3. The comments for packages, functions, methods and types are all in a complete sentence. 4. The first letters of sentence type comments must be capitalized; the first letters of phrase type comments must be lowercase. 5. The length of a single line of comments cannot exceed 80 characters.

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

The meaning of comments

• Comments can help us complete the document work well. Well-written comments can facilitate our future maintenance. . There are two comment styles: block comments of

• /**/ and single-line comments of //. In our project, for the sake of style Unified, all single-line comments are used, and the quality of the comments determines the quality of the generated documents.

Comment specifications

• All exported objects need to be commented to explain their purpose; non-exported objects are commented according to the situation.

• If the object is countable and the quantity is not explicitly specified, always use the singular form and the continuous continuous tense description; otherwise, use the plural form.

• Comments for packages, functions, methods, and types are all complete sentences.

• The first letters of sentence type comments must be capitalized; the first letters of phrase type comments must be lowercase.

• The length of a single line of comments cannot exceed 80 characters.

1. Package level

Package-level comments are an introduction to the package and only need to be included in any source file of the same package. Description is valid. [Related recommendations: Go video tutorial, Programming teaching]

• Each package should have a package comment, one in the package clause The previous line comment

• package comment should contain the following basic information

// @Title  请填写文件名称（需要改）
// @Description  请填写文件描述（需要改）
// @Author  请填写自己的真是姓名（需要改）  ${DATE} ${TIME}
// @Update  请填写自己的真是姓名（需要改）  ${DATE} ${TIME}
package ${GO_PACKAGE_NAME}

2. Structure (interface) comment

Each custom structure or interface should have a comment. The comment briefly introduces the structure and is placed on the line before the structure definition. The format is: structure name, structure description. At the same time, each member variable in the structure must have a description. The description is placed after the member variable (pay attention to alignment). The example is as follows:

// User   用户对象，定义了用户的基础信息
type User struct{
    Username  string // 用户名
    Email     string // 邮箱
}

3. Function (method) comment

• Each function or method (the function under the structure or interface is called a method) should have a comment

• The comment of the function should Including three aspects

// @title    函数名称
// @description   函数的详细描述
// @auth      作者             时间（2019/6/18   10:57 ）
// @param     输入参数名        参数类型         "解释"
// @return    返回参数名        参数类型         "解释"

4. Code logic comments

• A single line comment must be added to each code block

• Watch and use TODO. The details are as follows

// TODO  代码块的执行解释
if   userAge < 18 {

}

Other instructions

• When a certain part is waiting to be completed, a comment starting with TODO: can be used to remind the maintainer.

• When a certain part has a known problem that needs to be fixed or improved, you can use a comment starting with FIXME: to alert the maintainer.

• When you need to explain a problem in particular, you can use a comment starting with NOTE::

  // NOTE: os.Chmod and os.Chtimes don't recognize symbolic link,
  // which will lead "no such file or directory" error.
  return os.Symlink(target, dest)

More Programming For related knowledge, please visit: Introduction to Programming! !

The above is the detailed content of What is the comment coding specification of go language?. For more information, please follow other related articles on the PHP Chinese website!