In order to ensure the consistency and readability of the entire project, we have made more strict and detailed changes to the annotation specifications.
Be sure to pay attention to code comments when reviewing PR.
The meaning of the annotation
- Comments can help us complete the document work well. Well-written comments can facilitate our future maintenance and make it easier for new people to start the project better and faster.
- Good comments should be concise and clear, properly commented, carefully measured, not obscure or redundant.
- "Excellent code should be self-explanatory, and good code itself is a comment." If you can't do that, please add comments.
Overall annotation requirements
(1) Comments must be made in English only , and characters should be strictly separated by spaces.
(2) Except for package comments, which use /**/ multi-line comments, other comment styles should use single-line comments //.
Example:
Bad:
/**
...
**/
func listUser() error{
...
}
Good:
// listUser lists all users of department
func listUser() error{
...
}
(3) Single-line comments should not be too long, should be consistent with the code style, and should not exceed 120 characters; if it exceeds, please use line breaks to display, and try to keep the format elegant and easy to read.
(4) The comment marker and comment content in a single-line comment should be separated by a single space.
Example :
Good:
// listUser lists all users of department
func listUser() error{
...
}
Bad:
//listUser lists all users of department
func listUser() error{
...
}
(5) All comments should be in the third person singular.
Example:
Bad:
// listUser list all users of department
func listUser() error{
...
}
(6) In the code, please avoid commenting every line of code. Control the number of comments and improve the quality of the comments.
The annotation style strictly follows the above requirements.
File comments
- Each file should have a file comment at the very beginning of the file
- A file comment contains at least the following basic information, (whether it should include file description information Description)
/*
* Author: xiexiaoyu
*
* START DATE: 2023/2/25 14:28
*
* CONTACT: [email protected]
*/
File comments should be automatically commented through the code comment template. The comment template in Goland should be:
/*
* Author: xiexiaoyu
*
* START DATE: ${DATE} ${TIME}
*
* CONTACT: [email protected]
*/
package ${
GO_PACKAGE_NAME}
Structural (interface) comments
(1) 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.
(2) If the structure has many attributes, add comments to each member variable in the structure.
// User defines user info
type User struct {
// user name
Username string
// email
Email string
}
In some structures, some simple conventional fields may not be annotated, such as:
Name
Email
......
However, it should be noted that when a structure has some fields that are easily confused, even if the fields are simple, they should be annotated to distinguish them.
Example:
Good：
type PermissionModel struct {
UGID string
Path string
Method string
// english name
Nickname string
Pid string
}
Bad:
Like the example below, all fields are uncommented, and many fields are proprietary nouns in the module. People who read the code are confused.
type yciRepo struct {
db *Data
cron *gron.Cron
vmCache *go_cache.Cache
sc string
snapshotClass string
mlockImg string
consul string
remoteProm string
vmWhiteLIst []string
log *log.Helper
operator map[string]func(yciID string) error
}
(3) If it is an interface, describe it in the following way:
// FileInfo is the interface that describes a file and is returned by Stat and Lstat.
type FileInfo interface {
}
Example:
Good
Bad:
No comments
type UserRepo interface {
SSOLogin(ctx context.Context, ticket string) (*Token, error)
GetWxUserInfo(ctx context.Context, uid string) (*WxUserInfo, error)
GetUserInfo(ctx context.Context, uid string) (*Member, error)
ListRandomUsers(ctx context.Context, num int32) ([]*MemberMeta, error)
ListRecommendUsers(ctx context.Context, num int32) ([]*MemberMeta, error)
UpdateUserTags(ctx context.Context, uid string, tags []string) error
UpdateUserAvatarUrl(ctx context.Context, uid, avatarUrl string) error
}
Function (method) comments
(1) Each function or method (functions under a structure or interface are called methods) should have a comment.
(2) Function comments do not distinguish between uppercase functions and lowercase functions, especially some more complex functions, which must be commented
Example :
Bad：
func (u *userRepo) syncUsers() {
...
}
Function comments are not case sensitive and should give a detailed description of the function, except for extremely simple ones.
Good：
// syncUsers ...
// step1: ...
// step2: ...
// step3: ...
func (u *userRepo) syncUsers() {
...
}
(3) The first word of the comment should be consistent with the function name
// Dial connects to the address on the named network.
func Dial(network, address string) (Conn, error) {
...
}
(4) If examples in function or method comments can better clarify function usage and intent, please add appropriate examples.
// Dial connects to the address on the named network.
//
// Known networks are "tcp", "tcp4" (IPv4-only), "tcp6" (IPv6-only),
// "udp", "udp4" (IPv4-only), "udp6" (IPv6-only), "ip", "ip4"
// (IPv4-only), "ip6" (IPv6-only), "unix", "unixgram" and
// "unixpacket".
//
// Examples:
// Dial("tcp", "golang.org:http")
// Dial("tcp", "192.0.2.1:http")
// Dial("tcp", "198.51.100.1:80")
// Dial("udp", "[2001:db8::1]:domain")
// Dial("udp", "[fe80::1%lo0]:53")
// Dial("tcp", ":80")
func Dial(network, address string) (Conn, error) {
}
Code block comments
- Each code block represents a code logic and should be added with a single line comment
// 代码块的执行逻辑
if result > 0 {
}
- Error handling generally does not have comments
if err != nil {
}
Variable and global constant comments
- Each constant (const) and global variable (var) should be commented
- The first word of the comment should be consistent with the variable name and constant name
const (
// ID is the identifier of container
ID = "id"
)
other instructions
(1) When a certain part is waiting to be completed, a comment starting with TODO(name): can be used to remind the developer.
func GetComment(ctx context.Context, objId string) ([]*biz.CommentMeta, error) {
// TODO(xiexiaoyu): add limit and offset
...
}
(2) When there are known problems in a certain part that need to be fixed or improved, a comment starting with FIXME: can be used to remind the developer.
func DeleteComment(ctx context.Context, uid, objId string, id int) error {
// FIXME(xiexiaoyu): delete comment
...
}
(3) When a special issue needs to be explained, a comment starting with NOTE: can be used:
// 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)