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. 什么注释算是好注释

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

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

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

描述简洁，避免长篇大论

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

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

保留关键上下文信息

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

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

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

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

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