← 返回刚才阅读的位置

知识卡片

普通读书笔记卡 · 3905.b

导出声明注释以名字起句

理解等级:中级

导出名字(首字母大写、其他包可以使用)应有紧邻的文档注释,首句用被声明的名字开头并概括其作用。这样生成的文档即使脱离源码,也能把描述与对象对应起来。书中查找正则解析函数时运行 godoc regexp | grep parse:注释若写成 Compile parses a regular expression...,搜 parse 仍能看到名字 Compile;若每条都以“这个函数……”起句,就搜不回那个名字。

这张卡片看不懂?

已有反馈 · 0 条

    还没有人提交反馈。

    在整书笔记中的位置

    原书出处 · 1 处

    • 注释 · 查看原书依据

      程序中每一个被导出的(大写的)名字,都应该有一个文档注释。 文档注释作为完整的语句可以工作的最好,可以允许各种自动化的展现。第一条语句应该为一条概括语句,并且使用被声明的名字作为开头。

    参考来源

    - 位置:《Effective Go中文版》第03章《注释》(源文件:`_epub-src/OEBPS/注释.md.html`) - 结论依据:原文明确要求被导出的名字有文档注释,首句以声明名起头,并通过 `godoc regexp | grep parse` 展示这样写的可检索性。 - 原始内容:程序中每一个被导出的(大写的)名字,都应该有一个文档注释。文档注释作为完整的语句可以工作的最好,可以允许各种自动化的展现。第一条语句应该为一条概括语句,并且使用被声明的名字作为开头。