为改善Python代码质量提建议,今天我

在Python中有3种形式的代码注释:

1.块注释

2.行注释

3.文档注释(docstring)

使用场景介绍:

1.使用块或者行注释的时候仅仅注释那些复杂的操作、算法,还有可能别人难以理解

的技巧或者不够一目了然的代码。

2.注释和代码隔开一定的距离,同时在块注释之后最好多留几行空白再写代码。下面

两行代码显然第一行的阅读性要好。

例子:

x=x+1#increaceby1

x=x+1#increaceby1

3.给外部可访问的函数和方法(无论是否简单)添加文档注释。注释要清楚地描述方

法的功能,并对参数、返回值以及可能发生的异常进行说明,使得外部调用它的人员仅仅看

docstring就能正确使用。较为复杂的内部方法也需要进行注释推荐的函数注释如下

4.推荐在文件头中包含copyright申明、模块描述等,如有必要,可以考虑加作者信

息以及变更记录。

有人说,写代码就像写诗,你见过谁在自己写的诗里加注释吗?

这种说法受到许多人的追捧,包括一些Python程序员。

但我的看法是,代码跟诗不太一样,需要适当添加注释。

注释直接关系到代码的可读性和可维护性,

同时它还能够帮助发现错误的藏身之处。

因为代码是说明你怎么做的,而好的注释能够说清楚你想做什么,它们相输相成。

但往往有些程序员并不重视它,原因是多方面的,

有人觉得程序的实现才是最重要的,至于注释是一件浪费时间的事情;

还有的人明明知道注释很重要,可是太懒,不愿意写或者随便付;

也有人重视注释但却不得要领,反而使其成为代码的一种累赞。

下面针对以上几个心态举几个常见例子。

其他比较常见的问题还包括:

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

笑话归笑话,但是工作中,还是相互协作,有个编码规范,正所谓,大家好才是真的好!




转载请注明:http://www.aierlanlan.com/rzgz/2227.html