高效GO语言编程-代码注释

更多免费Golang知识，欢迎加入Go宝典 | GOLANG ROADMAP
邀请码：Gopher-1035-0722

Go 语言支持C风格的块注释 /* */ 和C++风格的行注释 //。行注释更为常用，而块注释则主要用作包的注释，当然也可在禁用一大段代码时使用。

godoc 既是一个程序，又是一个 Web 服务器，它对 Go 的源码进行处理，并提取包中的文档内容。出现在顶级声明之前，且与该声明之间没有空行的注释，将与该声明一起被提取出来，作为该条目的说明文档。这些注释的类型和风格决定了 godoc 生成的文档质量。

每个包都应包含一段包注释，即放置在包子句前的一个块注释。对于包含多个文件的包，包注释只需出现在其中的任一文件中即可。包注释应在整体上对该包进行介绍，并提供包的相关信息。它将出现在 godoc 页面中的最上面，并为紧随其后的内容建立详细的文档。

/*
regexp 包为正则表达式实现了一个简单的库。该库接受的正则表达式语法为：regexp:concatenation { '|' concatenation }concatenation:{ closure }closure:term [ '*' | '+' | '?' ]term:'^''$''.'character'[' [ '^' ] character-ranges ']''(' regexp ')'
*/
package regexp

若某个包比较简单，包注释同样可以简洁些。

// path 包实现了一些常用的工具，
// 以便于操作用反斜杠分隔的路径.

注释无需进行额外的格式化，如用星号来突出等。生成的输出甚至可能无法以等宽字体显示，因此不要依赖于空格对齐，godoc 会像 gofmt 那样处理好这一切。注释是不会被解析的纯文本，因此像HTML或其它类似于这样的东西将按照原样输出，因此不应使用它们。godoc 所做的调整，就是将已缩进的文本以等宽字体显示，来适应对应的程序片段。 fmt 包的注释就用了这种不错的效果。

godoc 是否会重新格式化注释取决于上下文，因此必须确保它们看起来清晰易辨：使用正确的拼写、标点和语句结构以及折叠长行等。

在包中，任何顶级声明前面的注释都将作为该声明的文档注释。在程序中，每个可导出（首字母大写）的名称都应该有文档注释。

文档注释最好是完整的句子，这样它才能适应各种自动化的展示。第一句应当以被声明的东西开头，并且是单句的摘要

// Compile 用于解析正则表达式并返回，如果成
// 功，则 Regexp 对象就可用于匹配所针对的文本。
func Compile(str string) (*Regexp, error) {

若注释总是以名称开头，go doc 命令的输出就能通过 grep 变得更加有用。假如你记不住 Compile 这个名称，而又在找正则表达式的解析函数（『解析』意味着关键词为 parse），那就可以运行

$ go doc -all regexp | grep -i parse

若包中的所有文档注释都以 This function… 开头，grep 就无法帮你记住此名称。但由于每个包的文档注释都以其名称开头，你就能看到这样的内容，它能显示你正在寻找的词语。

$ go doc -all regexp | grep -i parseCompile parses a regular expression and returns, if successful, a RegexpMustCompile is like Compile but panics if the expression cannot be parsed.parsed. It simplifies safe initialization of global variables holding
$

Go的声明语法允许成组声明。单个文档注释应介绍一组相关的常量或变量。由于是整体声明，这种注释往往较为笼统。

// 表达式解析失败后返回错误代码
var (ErrInternal      = errors.New("regexp: internal error")ErrUnmatchedLpar = errors.New("regexp: unmatched '('")ErrUnmatchedRpar = errors.New("regexp: unmatched ')'")...
)

即便是对于私有名称，也可通过成组声明来表明各项间的关系，例如某一组由互斥体保护的变量。

// 表达式解析失败后返回错误代码
var (ErrInternal      = errors.New("regexp: internal error")ErrUnmatchedLpar = errors.New("regexp: unmatched '('")ErrUnmatchedRpar = errors.New("regexp: unmatched ')'")...
)

更多免费Golang知识，欢迎加入Go宝典 | GOLANG ROADMAP
邀请码：Gopher-1035-0722

高效GO语言编程-代码注释相关推荐

python语言的注释语句引导符不包括什么_以下选项中,哪一个是Python语言中代码注释使用的符号?________...
[单选题]关于 Python 语句 P = –P,以下选项中描述正确的是________ [多选题]Python的数字类型包括( ) [多选题]Python中的注释符有哪几种?( ) [判断题]已知 ...
c语言编程代码大全(c语言简单代码大全)
html代码和c语言等编程语言有什么联系吗? HTML叫做超文本标记语言(标准通用标记语言下的一个应用)或超文本链接标示语言,是目前网络上应用最为广泛的语言,也是构成网页文档的主要语言. 怎么修改C语 ...
python语言中代码注释可以使用_以下选项中，Python语言中代码注释使用的符号是: ( )...
以下选项中,Python语言中代码注释使用的符号是: ( ) 答:# 中国古代舞蹈灿烂辉煌,但在理论研究方面却相对薄弱,这种情况直到明清都无显著改变. 答:错误 Photoshop中下列工具中不可以定 ...
C语言编程代码——因式分解
C语言编程代码--因式分解题目代码题目因式分解 Time Limit: 1000 ms Memory Limit: 65536 KiB Submit Statistic Problem Des ...
飞思卡尔单片机编程与c语言,飞思卡尔单片机高效C语言编程(中文)
高效C语言编程实验,包括:CodeWarrior的使用.中断.数据段的定义.常量数据段.变量.位操作.数组.指针.函数内的自变量.优化方法.Manual Optimization(手工优化).Proc ...
MPLAB-IDE-C语言编程代码实例-分析
以下学习笔记均使用C语言编程,编程软件为MPLAB IDEV8.89附加PICC18V9.66PRO版本.调试单片机采用pic18f14k22单片机. CONFIG __CONFIG();此段代码为P ...
万年历c语言编程代码_C语言高效编程与代码优化~
译文链接:http://www.codeceo.com/article/c-high-performance-coding.html 英文原文:https://www.codeproject.com/ ...
c语言注释含义,C语言编程规范——注释
前言制定C语言的编程规范,对代码的清晰.简洁.可测试.安全.程序效率.可移植各个方面有巨大的作用. 良好的注释能让整个代码读起来更加流畅,此乃程序猿出差旅行,通宵熬夜必备良药...... 注释的原则 ...
c语言git代码注释风格,git代码格式化上传
引言遇到的问题在项目开发过程中,缩进的配置.代码的最大长度.空格换行的使用不统一导致代码风格不一致,尤其是在一个团队中多人协作时,每个人有自己的编码风格,最终导致代码可读性差,难以维护. 是否有一 ...

高效GO语言编程-代码注释

高效GO语言编程-代码注释相关推荐

最新文章

热门文章