文档和注释的关系是?

文档包括注释?注释包括文档?还是有一个更宽泛的概念包括这两者?

(这里的「文档」指的是嵌在代码文件里的各种解释性的文本,而不是独立于代码文件之外的手册式文档)

文档是给别人看的

注释是给自己看的

文档是接口 注释是实现

文档是可见的 注释是私有的

好的文档什么样我不知道

但好的注释应该是 不写注释

无论语言再怎么简洁易懂,程序再怎么优雅,代码一定还是会有没法一眼看懂的地方。这时候注释能消除歧义和解释。

例子:

变量名,尤其是本地变量名一般不会太长,毕竟太长的话,用在代码各处反而导致可读性变低。所以一般不能把变量的作用限制注意事项全写在变量名里,而是起一个符合直觉的名字,再用注释解释。

数学运算(尤其是lisp里的)一般会用注释写上容易看懂的表达式

用注释解释为什么用了A实现而不是B实现

用注释解释函数的大体实现,有几步,都干了啥

等等

1 个赞

guifan

文档是给不关心你实现,只想调用的人看的。

注释是给关心你内部实现的人看的

注释的粒度更小,文档的粒度更大。一般注释一个变量,注释一个函数。给软件的一个模块写文档。

Doxygen 说文档等于代码+注释。。。

说的好,今年学会了这个技能