聊聊Go语言的注释

文章目录

  • 聊聊Go语言的注释
    • 一、注释的格式
      • 1.1 块注释
      • 1.2 行注释
    • 二、包注释
    • 三、命令注释
    • 四、类型注释
      • 4.1 实例注释
      • 4.2 并发安全注释
      • 4.3 零值注释
      • 4.4 导出字段注释
    • 五、函数注释
      • 5.1 参数/返回值/函数作用注释
      • 5.2 bool返回值函数注释
      • 5.3 形参/返回值名称注释
      • 5.4 并发安全注释
      • 5.5 特殊例子注释
      • 5.6 算法功能注释
    • 六、常量/变量注释
      • 6.1 分组注释
      • 6.2 组内元素注释
      • 6.3 未分组元素注释
      • 6.4 类型化元素注释

聊聊Go语言的注释

​ 在我们着手编写Go代码的时候,是否有过考虑,该编写什么样的代码注释才会使得代码读起来易懂呢?不会出现我们经常开玩笑说的:"过了几个月,自己写的代码都不认识了"的情况呢?

​ 接下来让我们一起来聊聊Go语言的注释,包括了包注释、命令注释、类型注释、函数注释、变量/常量注释部分,希望能够帮助大家养成良好注释的习惯!

一、注释的格式

​ 在Go语言中支持以下两种注释格式:

1.1 块注释

/**/是C风格的注释,常用于包的说明文档。同时在表达式中或者禁用大量的代码块非常有用。

/*
Package fmt implements formatted I/O with functions analogous
to C's printf and scanf.  The format 'verbs' are derived from C's but
are simpler.
.....
*/
package fmt

注:在Go语言包中的doc.go通常是包的文档性说明。

1.2 行注释

//是C++风格注释,在Go语言中比较常用。

// A fmt is the raw formatter used by Printf etc.
// It prints into a buffer that must be set up separately.
type fmt struct {buf *buffer...
}

二、包注释

​ 每个程序包(Package)都应该有一个包注释,该注释介绍了整个Package相关的信息,并且通常设定了对Package的期望效果。

​ 包注释不仅仅可以使用块注释的格式,当然也可以使用行注释的格式,这两种格式在Go语言中都非常常用。

// Package path implements utility routines for manipulating slash-separated
// paths.
//
// The path package should only be used for paths separated by forward
// slashes, such as the paths in URLs. This package does not deal with
// Windows paths with drive letters or backslashes; to manipulate
// operating system paths, use the [path/filepath] package.
package path

​ 让我们来解释一下示例中的包注释:

  • 包注释的第一句话

    1. // Package path:这是一个包注释,用于描述接下来的代码文件是一个名为path的包。这是Go语言约定的一部分,有助于在整个代码库中提供一致的文档。也就是说开头必须声明这个Package,Package后面接着是包的名称。
    2. implements utility routines for manipulating slash-separated paths.:这是对包功能的简要描述。它说明了该包的目的,即实现用于处理斜杠分隔路径的实用程序例程。
  • 包注释的其它语句

    1. 主要是针对包的功能具体使用方法进行一个说明。

    2. 当然也可以添加包的使用示例(可选)

      /*
      ....
      For example,fmt.Sprintf("%[2]d %[1]d\n", 11, 22)will yield "22 11", whilefmt.Sprintf("%[3]*.[2]*[1]f", 12.0, 2, 6)equivalent tofmt.Sprintf("%6.2f", 12.0)
      ....
      */
      package fmt
      

三、命令注释

​ 命令(Command)注释与包注释,但它描述的是程序的行为,而不是程序包中的功能特征。注释的第一句话的开头通常是Command的名称,需要首字母大写(因为是一行的开头)

/*
Gofmt formats Go programs.
It uses tabs for indentation and blanks for alignment.
Alignment assumes that an editor is using a fixed-width font.
...
Usage:gofmt [flags] [path ...]The flags are:-dDo not print reformatted sources to standard output.If a file's formatting is different than gofmt's, print diffsto standard output.-wDo not print reformatted sources to standard output.If a file's formatting is different from gofmt's, overwrite itwith gofmt's version. If an error occurred during overwriting,the original file is restored from an automatic backup.
...
*/
package main

​ 注:命令注释通常使用块注释来表示,内容主要包括:命令的功能、命令的用法及参数说明等。

四、类型注释

4.1 实例注释

​ 类型(type)注释应该解释type中的每个实例代表了什么。注释的第一句话的开头通常是type的名称或者添加一个A,需要首字母大写(因为是一行的开头)

package zip// A Reader serves content from a ZIP archive.
type Reader struct {...
}

4.2 并发安全注释

默认情况下,一个类型被单个goroutine使用是安全的,如果一个类型支持并发使用的话,那么文档注释应该说明它。

package regexp// Regexp is the representation of a compiled regular expression.
// A Regexp is safe for concurrent use by multiple goroutines,
// except for configuration methods, such as Longest.
type Regexp struct {...
}

4.3 零值注释

如果一个类型的零值是有意义的,那么也应当进行说明

package bytes// A Buffer is a variable-sized buffer of bytes with Read and Write methods.
// The zero value for Buffer is an empty buffer ready to use.
type Buffer struct {...
}

4.4 导出字段注释

对于类型中的每一个具有导出意义的字段(也就是开头首字母是大写)都应该进行说明

package io// A LimitedReader reads from R but limits the amount of
// data returned to just N bytes. Each call to Read
// updates N to reflect the new amount remaining.
// Read returns EOF when N <= 0.
type LimitedReader struct {R   Reader // underlying readerN   int64  // max bytes remaining
}

五、函数注释

5.1 参数/返回值/函数作用注释

​ 函数(func)注释应该解释函数的参数、返回值含义,同时应该解释函数的作用。

package strconv
// 例子1:解释了返回值的含义和函数功能
// Quote returns a double-quoted Go string literal representing s.
// The returned string uses Go escape sequences (\t, \n, \xFF, \u0100)
// for control characters and non-printable characters as defined by IsPrint.
func Quote(s string) string {...
}
// 例子2:解释了参数的含义和函数功能
package os
// Exit causes the current program to exit with the given status code.
// Conventionally, code zero indicates success, non-zero an error.
// The program terminates immediately; deferred functions are not run.
//
// For portability, the status code should be in the range [0, 125].
func Exit(code int) {...
}

5.2 bool返回值函数注释

对于bool返回值的函数,通常使用reports whether来描述函数功能,而不是使用or not

package strings// HasPrefix reports whether the string s begins with prefix.
func HasPrefix(s, prefix string) bool

5.3 形参/返回值名称注释

函数的形参的命名和返回值的命名必须要见名知意,并且可以将它们添加到文档注释中,使得文档注释更容易理解。

package io// Copy copies from src to dst until either EOF is reached
// on src or an error occurs. It returns the total number of bytes
// written and the first error encountered while copying, if any.
//
// A successful Copy returns err == nil, not err == EOF.
// Because Copy is defined to read from src until EOF, it does
// not treat an EOF from Read as an error to be reported.
func Copy(dst Writer, src Reader) (n int64, err error) {...
}

5.4 并发安全注释

同样的,和类型注释一样,若函数是并发安全的,那么也需要在函数注释中说明。

package sql// Close returns the connection to the connection pool.
// All operations after a Close will return with ErrConnDone.
// Close is safe to call concurrently with other operations and will
// block until all other operations finish. It may be useful to first
// cancel any used context and then call Close directly after.
func (c *Conn) Close() error {...
}

5.5 特殊例子注释

当然,如果函数特殊例子,那么函数注释也应当说明:

package math// Sqrt returns the square root of x.
//
// Special cases are:
//
//  Sqrt(+Inf) = +Inf
//  Sqrt(±0) = ±0
//  Sqrt(x < 0) = NaN
//  Sqrt(NaN) = NaN
func Sqrt(x float64) float64 {...
}

5.6 算法功能注释

函数注释不应解释内部细节,例如当前实现中使用的算法。这些最好留给函数体内部的注释。这样做的好处是: 将来可以更加容易的将该函数更改为不同的算法,而不需要改动文档。

package sort// Sort sorts data in ascending order as determined by the Less method.
// It makes one call to data.Len to determine n and O(n*log(n)) calls to
// data.Less and data.Swap. The sort is not guaranteed to be stable.
func Sort(data Interface) {...
}

六、常量/变量注释

6.1 分组注释

​ 可以对常量(const)/变量(variable)进行分组表示,同时一般使用单行注释来说明。

package scanner // import "text/scanner"// The result of Scan is one of these tokens or a Unicode character.
const (EOF = -(iota + 1)IdentIntFloatChar...
)

6.2 组内元素注释

有时候,常量/变量里面的每一个元素都需要记录其作用

package unicode // import "unicode"const (MaxRune         = '\U0010FFFF' // maximum valid Unicode code point.ReplacementChar = '\uFFFD'     // represents invalid code points.MaxASCII        = '\u007F'     // maximum ASCII value.MaxLatin1       = '\u00FF'     // maximum Latin-1 value.
)

6.3 未分组元素注释

另一方面,未分组的常量/变量的注释开头通常为名称。例如:

package unicode// Version is the Unicode edition from which the tables are derived.
const Version = "13.0.0

6.4 类型化元素注释

类型化常量/变量显示在其类型的声明旁边,因此通常会省略常量/变量注释,而使用该类型的文档注释。

package syntax// An Op is a single regular expression operator.
type Op uint8const (OpNoMatch        Op = 1 + iota // matches no stringsOpEmptyMatch                   // matches empty stringOpLiteral                      // matches Runes sequenceOpCharClass                    // matches Runes interpreted as range pair listOpAnyCharNotNL                 // matches any character except newline...
)

​ 好啦,本文到此就结束喽!介绍了五种类型的注释方法,希望能对您编写良好的Go语言注释有所帮助。若文章中出现任何纰漏,欢迎大家指正批评哦!如果觉得写得还不错的话,麻烦大家点赞收藏加关注哦!

参考文章:
The Go Programming Language Specification

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/168757.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

分布式锁,分布式锁应该具备哪些条件,分布式锁的实现方式有:基于Zookeeper实现、Redis实现、数据库实现

文章目录 分布式锁0-1分布式锁--包含CAP理论模型概述分布式锁&#xff1a;分布式锁应该具备哪些条件&#xff1a;分布式锁的业务场景&#xff1a; 分布式锁的实现方式有&#xff1a;基于Zookeeper - 分布式锁实现思想优缺点基于Redis - 分布式锁实现思想实现思想的具体步骤&…

【LeetCode 热题 HOT 100】题解笔记 —— Day01

❤ 作者主页&#xff1a;欢迎来到我的技术博客&#x1f60e; ❀ 个人介绍&#xff1a;大家好&#xff0c;本人热衷于Java后端开发&#xff0c;欢迎来交流学习哦&#xff01;(&#xffe3;▽&#xffe3;)~* &#x1f34a; 如果文章对您有帮助&#xff0c;记得关注、点赞、收藏、…

企业海外分部,如何实现安全稳定的跨境网络互连?

如今&#xff0c;众多企业广泛采取数字化业务系统&#xff0c;如OA、ERP及CRM等&#xff0c;来提升其业务运营效率。同时&#xff0c;私有云与公有云混合架构也逐渐普及化。 具体来说&#xff0c;很多企业选择将研发系统部署在公司本地的私有云环境&#xff0c;以此确保数据安全…

首批!创邻科技入选《图数据库金融应用场景优秀案例》

11月11日&#xff0c;“全球金融科技中心网络年会”在第三届全球金融科技大会暨第五届成方金融科技论坛上成功在京举办。会上&#xff0c;北京前沿金融监管科技研究院发布了基于国际标准组织——国际关联数据基准委员会&#xff08;LDBC&#xff09;的《图数据库金融应用场景优…

路由器DHCP分配IP地址规则

路由器DHCP分配IP地址的机制&#xff1a; 先设置一个IP地址池&#xff0c;假设是192.168.1.100-192.168.1.199一共100个。 来一个请求&#xff0c;看一下是不是以前请求过的地址&#xff0c;如果是&#xff0c;还是返回以前给过的IP&#xff0c;然后将到期时间(有些路由器默认…

【Python3】【力扣题】349. 两个数组的交集

【力扣题】题目描述&#xff1a; 【Python3】代码&#xff1a; 1、解题思路&#xff1a;集合的交集。两个数组都转为集合&#xff0c;获取集合的交集。 知识点&#xff1a;set(...)&#xff1a;转为集合&#xff0c;集合的元素不重复。 集合1.intersection(集合2)&#xff1a…

MySQL 中文转拼音函数

需求是将字符串中的汉字转为拼音。创建一个汉字转拼音的函数&#xff0c;在其中判断每个字符是否为中文&#xff0c;如果是则查询拼音表取得对应的拼音&#xff0c;否则原样返回。网上的大部分 MySQL 转拼音函数都是通过创建一个拼音对照表&#xff0c;然后在自定义函数中查询该…

Python3.7 win7系统安装openCV方案

为了使用机房电脑处理数字图像问题&#xff0c;在win7系统安装了python opencv, 测试使用的是官网下载python3.7.7版本&#xff0c;如果官网安装&#xff0c;直接安装即可 pip install python-opencv 这样会自动安装对应版本的numpy 如果官网安装很慢&#xff0c;想使用镜像安…

HTTP 响应头信息

HTTP 响应头信息 HTTP请求头提供了关于请求&#xff0c;响应或者其他的发送实体的信息。 在本章节中我们将具体来介绍HTTP响应头信息。 应答头说明Allow服务器支持哪些请求方法&#xff08;如GET、POST等&#xff09;。Content-Encoding文档的编码&#xff08;Encode&#x…

【Linux】EVIOCGBIT

EVIOCGBIT(ev, len) 该怎么理解&#xff1f; 我们可以推断出&#xff0c;它是一个宏&#xff0c;它的前两个参数已经确定了&#xff0c;具体的功能由后两个参数(ev,len)来决定。Linux-4.9.88\include\uapi\linux\input.h #define EVIOCGBIT(ev,len) _IOC(_IOC_READ, E, 0x20 …

记录问题-使用@Validated报错Validation failed for argument [0]

类字段 NotNull(message "双坐标不能为空", groups {Insert.class, Update.class})private Integer yAxisType;接口 /*** 添加** return*/RequestMapping(value "/add", method RequestMethod.POST)public Result add(Validated(Insert.class) Request…

如何申请文心一言文心千帆大模型API调用资格、获取access_token,并使用SpringBoot接入文心一言API

前段时间&#xff0c;百度文心一言&文心千帆大模型开放了API调用的测试&#xff0c;接下来&#xff0c;教大家申请测试资格并接入文心千帆大模型的API。 一、文心一言&文心千帆的测试资格申请 1. 确保拥有一个百度智能云的账号 右上角点击注册&#xff0c;内容如实填…

【知网稳定检索】第九届社会科学与经济发展国际学术会议 (ICSSED 2024)

第九届社会科学与经济发展国际学术会议 (ICSSED 2024) 2024 9th International Conference on Social Sciences and Economic Development 第九届社会科学与经济发展国际学术会议(ICSSED 2024)定于2024年3月22-24日在中国北京隆重举行。会议主要围绕社会科学与经济发展等研究…

postgresql从入门到精通 - 第35讲:中间件PgBouncer部署|PostgreSQL教程

PostgreSQL从小白到专家&#xff0c;是从入门逐渐能力提升的一个系列教程&#xff0c;内容包括对PG基础的认知、包括安装使用、包括角色权限、包括维护管理、、等内容&#xff0c;希望对热爱PG、学习PG的同学们有帮助&#xff0c;欢迎持续关注CUUG PG技术大讲堂。 第35讲&#…

一些数据库学习的小结

一些数据库学习的小结&#xff1a; SQL: 遵循ACID原则。支持Transaction。适合在线交易处理(OLTP)&#xff0c;不适合在线分析处理(OLAP)。例子有 MySQL POSTGRESQL NoSQL: 遵循BASE原则。不支持Transaction。例子有 DynamoDB - Amazon Key-Value BigTable - Google Cassandr…

webrtc兼容android4.x的一次探索

背景是我们有一个四年前的应用&#xff0c;该应用TargetVersion设定为16&#xff0c;这个应用四年前用了m70版本的webrtc。最近我升级到webrtc-m110&#xff0c;发现各种崩溃&#xff0c;把崩溃修好之后&#xff0c;发现黑屏了。为了处理黑屏&#xff0c;故有本文。 黑屏问题表…

荆涛《春节回家》:歌声中的年味与乡愁

荆涛《春节回家》&#xff1a;歌声中的年味与乡愁春节&#xff0c;对于每一个中国人来说&#xff0c;都是一年中最为重要的时刻。它不仅仅是一个节日&#xff0c;更是团圆、乡愁、回忆与希望的象征。歌手荆涛的歌曲《春节回家》恰恰捕捉到了这些情感&#xff0c;用音乐为人们绘…

hdlbits系列verilog解答(Exams/m2014 q4e)-46

文章目录 一、问题描述二、verilog源码三、仿真结果 一、问题描述 实现以下电路&#xff1a; 二、verilog源码 module top_module (input in1,input in2,output out);assign out ~(in1 | in2);endmodule三、仿真结果 转载请注明出处&#xff01;

【SpringBoot系列】SpringBoot日志配置

&#x1f49d;&#x1f49d;&#x1f49d;欢迎来到我的博客&#xff0c;很高兴能够在这里和您见面&#xff01;希望您在这里可以感受到一份轻松愉快的氛围&#xff0c;不仅可以获得有趣的内容和知识&#xff0c;也可以畅所欲言、分享您的想法和见解。 推荐:kwan 的首页,持续学…

hdlbits系列verilog解答(exams/m2014_q4i)-45

文章目录 一、问题描述二、verilog源码三、仿真结果 一、问题描述 实现以下电路&#xff1a; 二、verilog源码 module top_module (output out);assign out 1b0;endmodule三、仿真结果 转载请注明出处&#xff01;