如果你多了解一些编程语言,你就能够发现一个特别神奇的现象,所有的编程语言都允许你写注释,而在很多初学者眼中,注释并不是什么重要的东西,学习过程中几乎没有太多的关注。
但在实际工作中,注释是非常重要的,甚至有观点认为注释是程序的一部分,为什么在专业人士眼中,代码注释如此重要呢?其实原因很简单,你今天写的代码,7天以后你自己都不认识了。
就是这么不可思议,但又很合理,你还记得7天前晚饭吃的是什么?代码,是你大脑里逻辑的一种技术呈现,彼时彼刻,你所思所想浓缩成了一行行的代码,但是7天以后,这一行行代码却很难反向转换成你大脑里的逻辑,这就是写注释的必要所在。
注释的目的是解释代码在做什么,关键性的信息可以让你在回顾代码时回想起更多的更完整的信息。
对于初学者,给代码写注释,更有助于理清代码逻辑,让思维更严谨。
单行注释以 # 开头,根据规范,注释内容与# 间隔一个空格
count = 0 # 记录数量
多行注释,可以用三个单引号,或者三个双引号括起来
def recursion(number):
"""
计算number的阶乘
:param number:
:return:
"""
if number == 1:
return 1
next_recursion = recursion(number-1)
return next_recursion*number
if __name__ == '__main__':
print(recursion(4))
或者
def recursion(number):
'''
计算number的阶乘
:param number:
:return:
'''
多行注释多用于函数,类,模块
关于这个问题,没有标准答案,有人很抬杠的说代码是最好的注释,这等于没说,正是因为写出好代码不是一件容易的事情,所以,才要写注释。
结合我自身的工作经验,我认为好的代码注释应该符合以下几个特点
如果把一段代码注释写成了议论文,那岂不是喧宾夺主,注释应该简洁,减轻阅读负担。
注释内容要直观,比如给一个函数写注释,要简明的描述函数的功能和作用。
只有写代码的人才了解上下文信息,而对于维护代码的人来说,这些信息往往是缺失的,比如给一个函数写注释,如果函数是一个功能函数,那么注释应该说清楚它的适用范围,如果是一个对外的接口,那么应该说清楚目前谁在调用,入参需要注意的问题是什么。
保留这些上下文信息,可以让接手的人快速的了解这个函数,不至于到处去问人,
和第一条遥相呼应,代码做了什么,简明扼要的介绍就可以了,但是为什么要这么做则需要多做些说明。
如果接手代码的人不清楚为什么要这么做,很可能会以后你的代码写的有问题,因为他不了解需求背景,他不了解当初写代码时的考虑因素和限制条件,所以,注释应当为后来人释疑,让维护代码的人大胆放心的使用,而不是质疑你的代码