Question

Python中有3种形式的代码注释：块注释、行注释以及文档注释（docstring）。这3种形式的惯用法大概有如下几种：

1）使用块或者行注释的时候仅仅注释那些复杂的操作、算法，还有可能别人难以理解的技巧或者不够一目了然的代码。

2）注释和代码隔开一定的距离，同时在块注释之后最好多留几行空白再写代码。下面两行代码显然第一行的阅读性要好。

x=x+1    # increace x  by 1  
①
x=x+1 #increase x by 1       
②

3）给外部可访问的函数和方法（无论是否简单）添加文档注释。注释要清楚地描述方法的功能，并对参数、返回值以及可能发生的异常进行说明，使得外部调用它的人员仅仅看docstring就能正确使用。较为复杂的内部方法也需要进行注释。推荐的函数注释如下：

def FuncName(parameter1 , parameter2):
  """Describe what this function does. 
    #such as "Find whether the special string is in the queue or not"
    Args:
      parameter1: parameter type, what is this parameter used for. 
            #such as strqueue:string,string queue list for search
      parameter2: parameter type, what is this parameter used for.
            #such as str:string,string to find
  Returns:
      return type, return value.
      #such as  boolean,sepcial string  found return True,else return False
  """
    function body
    ...
    ...

4）推荐在文件头中包含copyright申明、模块描述等，如有必要，可以考虑加入作者信息以及变更记录。

"""
  Licensed Materials - Property of CorpA
  (C) Copyright A Corp. 1999, 2011 All Rights Reserved
  CopyRight statement and purpose...
--------------------------------------------------------------------------
File Name   : comments.py
Description : description what the main function of this file
Author: Author name
Change Activity:
    list the change activity and time and author information.
--------------------------------------------------------------------------
"""

有人说，写代码就像写诗，你见过谁在自己写的诗里加注释吗？这种说法受到许多人的追捧，包括一些Python程序员。但我的看法是，代码跟诗不太一样，需要适当添加注释。注释直接关系到代码的可读性和可维护性，同时它还能够帮助发现错误的藏身之处。因为代码是说明你怎么做的，而好的注释能够说清楚你想做什么，它们相辅相成。但往往有些程序员并不重视它，原因是多方面的，有人觉得程序的实现才是最重要的，至于注释是一件浪费时间的事情；还有的人明明知道注释很重要，可是太懒，不愿意写或者随便应付；也有人重视注释但却不得要领，反而使其成为代码的一种累赘。下面针对以上几个心态举几个实际中常见例子。

示例一：代码即注释（不写注释）。没有注释的代码通常会给他人的阅读和理解带来一定困难，即使是自己写的代码，过一段时间再回头阅读可能也需要一定时间才能理解当初的思路。

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

其他比较常见的问题还包括：代码不断更新而注释却没有更新；注释比代码本身还复杂烦琐；将别处的注释和代码一起拷贝过来，但上下文的变更导致注释与代码不同步；更有个别人将注释当做自己的娱乐空间从而留下个性特征等，这几种行为都是平时要注意避免的。