在Python中有3种形式的代码注释:
1.块注释
2.行注释
3.文档注释(docstring)
使用场景介绍:
1.使用块或者行注释的时候仅仅注释那些复杂的操作、算法,还有可能别人难以理解
的技巧或者不够一目了然的代码。
2.注释和代码隔开一定的距离,同时在块注释之后最好多留几行空白再写代码。下面
两行代码显然第一行的阅读性要好。
例子:
x=x+1#increaceby1
x=x+1#increaceby1
3.给外部可访问的函数和方法(无论是否简单)添加文档注释。注释要清楚地描述方
法的功能,并对参数、返回值以及可能发生的异常进行说明,使得外部调用它的人员仅仅看
docstring就能正确使用。较为复杂的内部方法也需要进行注释推荐的函数注释如下
4.推荐在文件头中包含copyright申明、模块描述等,如有必要,可以考虑加作者信
息以及变更记录。
有人说,写代码就像写诗,你见过谁在自己写的诗里加注释吗?
这种说法受到许多人的追捧,包括一些Python程序员。
但我的看法是,代码跟诗不太一样,需要适当添加注释。
注释直接关系到代码的可读性和可维护性,
同时它还能够帮助发现错误的藏身之处。
因为代码是说明你怎么做的,而好的注释能够说清楚你想做什么,它们相输相成。
但往往有些程序员并不重视它,原因是多方面的,
有人觉得程序的实现才是最重要的,至于注释是一件浪费时间的事情;
还有的人明明知道注释很重要,可是太懒,不愿意写或者随便付;
也有人重视注释但却不得要领,反而使其成为代码的一种累赞。
下面针对以上几个心态举几个常见例子。
其他比较常见的问题还包括:
代码不断更新而注释却没有更新;注释比代码本身还复杂烦琐;将别处的注释和代码一起拷贝过来,但上下文的变更导致注释与代码不同步;更有个别人将注释当作自己的娱乐空间从而留下个性特征等,这几种行为都是平时要注意避免的。
笑话归笑话,但是工作中,还是相互协作,有个编码规范,正所谓,大家好才是真的好!