python如何写注释

1. 为什么要写注释

如果你多了解一些编程语言,你就能够发现一个特别神奇的现象,所有的编程语言都允许你写注释,而在很多初学者眼中,注释并不是什么重要的东西,学习过程中几乎没有太多的关注。

但在实际工作中,注释是非常重要的,甚至有观点认为注释是程序的一部分,为什么在专业人士眼中,代码注释如此重要呢?其实原因很简单,你今天写的代码,7天以后你自己都不认识了。

就是这么不可思议,但又很合理,你还记得7天前晚饭吃的是什么?代码,是你大脑里逻辑的一种技术呈现,彼时彼刻,你所思所想浓缩成了一行行的代码,但是7天以后,这一行行代码却很难反向转换成你大脑里的逻辑,这就是写注释的必要所在。

注释的目的是解释代码在做什么,关键性的信息可以让你在回顾代码时回想起更多的更完整的信息。

对于初学者,给代码写注释,更有助于理清代码逻辑,让思维更严谨。

2. 注释的写法

2.1 单行注释

单行注释以 # 开头,根据规范,注释内容与# 间隔一个空格

count = 0   # 记录数量

2.2 多行注释

多行注释,可以用三个单引号,或者三个双引号括起来

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:
    '''

多行注释多用于函数,类,模块

3. 什么注释算是好注释

关于这个问题,没有标准答案,有人很抬杠的说代码是最好的注释,这等于没说,正是因为写出好代码不是一件容易的事情,所以,才要写注释。

结合我自身的工作经验,我认为好的代码注释应该符合以下几个特点

  1. 描述简洁,避免长篇大论
  2. 保留关键上下文信息
  3. 多记录为什么,少说是什么

描述简洁,避免长篇大论

如果把一段代码注释写成了议论文,那岂不是喧宾夺主,注释应该简洁,减轻阅读负担。

注释内容要直观,比如给一个函数写注释,要简明的描述函数的功能和作用。

保留关键上下文信息

只有写代码的人才了解上下文信息,而对于维护代码的人来说,这些信息往往是缺失的,比如给一个函数写注释,如果函数是一个功能函数,那么注释应该说清楚它的适用范围,如果是一个对外的接口,那么应该说清楚目前谁在调用,入参需要注意的问题是什么。

保留这些上下文信息,可以让接手的人快速的了解这个函数,不至于到处去问人,

多记录为什么,少说是什么

和第一条遥相呼应,代码做了什么,简明扼要的介绍就可以了,但是为什么要这么做则需要多做些说明。

如果接手代码的人不清楚为什么要这么做,很可能会认为你的代码写的有问题,因为他不了解需求背景,他不了解当初写代码时的考虑因素和限制条件,所以,注释应当为后来人释疑,让维护代码的人大胆放心的使用,而不是质疑你的代码

扫描关注, 与我技术互动

QQ交流群: 211426309

加入知识星球, 每天收获更多精彩内容

分享日常研究的python技术和遇到的问题及解决方案