随笔 | python中注释和文档字符串的共同点和区别

1.注释和文档字符串：

python中注释和文档字符串能够帮助程序员理解程序编写者的代码，我们在使用python中经常会用到这两个功能，必要的注释和文档字符串甚至是一个优秀程序的必要条件。但是可能有人跟我一样对两者的区别产生疑惑，如果他们都是起说明解释的作用，为什么不用注释代替文档字符串呢？他们在相似的同时有什么区别呢？请往下读

2.两者区别：

• 注释和文档字符串（docstrings）的区别主要在于文档字符串是可以调用的，而注释不行。

比如下面这个简单的函数：

#定义一个带有文档字符串的简单函数
def print_hello():
    ”“”this funtion is to print hello “”“
    
    print（‘hello’）
#下面我们来调用并输出文档字符串
print（print__hello.__doc__)

运行这个函数，得到下面的结果：

通过上面的程序我们可以看到函数把文档字符串打印在了屏幕上。我们来分析这个程序：我们先定义了一个简单函数print_hello，添加了文档字符串，如你看到的。然后在代码的最后一行我们打印了该函数的__doc__属性，该属性与你定义的函数下面的文档字符串相关联，并能在你调用的时候输出。值得一提的是，我们经常使用命令‘help（函数名）’来获取该函数的有关说明和帮助，而它的就是上面提到的。
在下面这个例子中，我使用了内置函数help来获取str函数（同样是内置函数，用来将非字符串数值转化为字符串数值）的说明。照上面来看，help实际上就是起到获取内置函数的文档字符串的作用。

因此docstrings是可以调用的，而注释不行

• 注释和文档字符串的另一个区别是，文档字符串一般是在定义新函数或者新的类的下一行使用，起到说明作用，这是一种规范，是约定俗成的。而注释相比之下更随意一些，在任何地方，只要不会使代码出错，都可以使用注释。所以文档字符串是属于函数代码块里的，它必须要缩进，否则就会出错。

def print_hello():
#现在文档字符串没有缩进，看看会发生什么
”“”this funtion is to print hello “”“
    
    print（‘hello’）
#下面我们来调用并输出文档字符串
print（print__hello.__doc__)

运行：

发生了缩进错误。
值得一提的是，文档字符串既可以用三引号（”“”）亦可以用三撇号（’‘’），这两个方式是等效的。
如下图：

3.相同点：
注释和文档字符串的相同点点主要体现在以下两点：

1. 起到解释说明作用
2. 不会影响代码的正常运行

总之，要想写出易于理解的优秀代码，注释和文档字符串必不可少，它们使你的代码让人更加容易读懂，而你在读别人的代码时，他们的注释和文档字符串也对你理解代码上起到重要的作用。