什么是好的程序注释

作者:, 发表于

以前总是被教育说注释写得越详细越好,我自己写代码的时候也恨不得将每一步都用自然语言给它翻译一遍,如果没写注释就觉得不专业。后来看到健硕写的notes,再加上最近做一个东西,也有一些感受。

注释,是为了给自己和别人在下次浏览代码的时候用的,它主要解决三个问题:

1、what:下面代码是干嘛用的
2、How:下面代码是怎么做的
3、Why:为何要写这段代码(为何要这么做)

精确的注释,主要解释清楚第三点:为什么要写这段代码。关于What和How的注释应该是代码本身。

比如一段代码将一个矩阵排序,一个code reviewer看到这段代码时,他需要知道为什么要排序,排序对后续代码有什么影响。而第一点和第二点更多是通过代码本身得到而不需要再写注释去描述了。比如调用了sort,即明确说明该段代码是在排序,而调用quicksort则是用快速排序法给矩阵排序。

 

Q.E.D.


上一篇:Access和SQL Server的语法区别2014年11月1日
总结了Access和SQL Server语法的差异。

下一篇:让InstantClick兼容MathJax、百度统计等2014年12月25日
之前有网友提及博客上的LaTex(由MathJax实现)坏掉了,其原因是这里使用了instantclick,以达到网页秒开的效果。但由于instantclick不会重新运行位于head部


  • 支持使用微薄、微信和QQ的账户登陆进行评论。由各自网站直接认证,不会泄露你的密码。
  • 登陆后可选择分享评论到所绑定的社交网络,如微薄、人人和QQ空间。
  • 评论提交后无法修改。如需修改,请删除原评论再重新提交。
  • 评论支持LaTeX代码,行内公式请用\(a+b=c\),行间公式请用\[a+b=c\]。公式只支持英文字符。