【原】代码注释的几个误区

东北十三少 2020-10-16

展开全文

在我们所见的编码规范中，几乎都会要求代码要有注释，注释率应达到20%以上。

所以如此，是因为好的注释能够提高代码的可读性和可维护性。

可是，在实践中，即使是那些实施GJB5000A三级体系的组织，对代码注释都没有足够的重视：或者根本不写注释，或者对注释应付了事。像下面这样的说法也受到很多人的追捧：

写代码就像写诗，你见过谁在自己写的诗里加注释吗？

尽管这种说法把码农变成了诗人，但是代码毕竟跟诗不太一样，有注释的代码不仅会提高代码的可读性和可维护性，同时它还能够帮助发现代码中隐藏的错误。

下面罗列几个常见的对代码注释理解不正确的例子。

误区一：代码即注释（换句话说就是不写注释）。

没有注释的代码，特别是那些连变更名也不好好命名的代码，通常会让人难以理解，时间一长，即使是自己写的代码，可能也不明白它要实现的意图。

比如下面这样的代码：

a=3
n=5
count,sn,tn=1,0,0
while count<=n:
.      tn+=a
       sn+=tn
       a*=10
       count+=1
print sn

误区二：注释与代码重复。

好的注释是用来解释代码的功能以及设计师的想法的，而不是对代码本身的解释。像下面这样的注释就没有任何意义，只是给代码徒增一些累赘。

# coding=utf-8
print "please input number n"
n=input()
print "please input number m"
m=input()
t=n/2                   # t
是n
的一半
#
循环，条件为t*m/n
小于n
while(t*m/(n+1) < n):
        t=0.5*m+n/2     #
重新计算t
值
        print t

示例三：利用注释语法快速删除代码。

这种情况也是程序员们常见的做法。在软件调试过程中，为了快速验证一种新的思路，程序员们会将原有的代码注释掉，这样一旦新的思路行不通的时候，可以快速恢复原来的设计。而实际上，如果你做好配置管理，你大可不必担心删除的代码找不回来。无用的代码该删除就要删除，用注释的方式删除代码，很可能最终把这些垃圾遗留在代码中。

就像这样：

x=2
y=5
z=3
"""following code is no longer needed since there is a better way
if x>y:t=x;x=y;y=t
if x>z:t=z;z=x;x=t
if y>z:t=y;y=z;z=t
print "the order from small to big is: %d %d %d" % (x,y,z)
"""
order_list=[x,y,z]
order_list.sort()
print order_list