python文档注释符是什么_Python为什么用#号作注释符？

关于编程语言中的注释&＃xff0c;其重要性基本上已为大家所共识。

然而关于注释的规范&＃xff0c;这个话题就像我们之前聊过的缩进、终止符和命名方式一样&＃xff0c;众口难调。

注释符通常可分为两种&＃xff0c;即行注释与块注释(inline/block)&＃xff0c;它们在不同的编程语言中的符号可谓让人眼花缭乱。

比如行注释符&＃xff0c;它至少有以下的 17 种之多(出自维基百科)&＃xff1a;

其中两个最大的阵营分别是“//”与“#”号&＃xff1a;

// 注释符&＃xff1a;ActionScript, C (C99), C&＃43;&＃43;, C#, D, F#, Go, Java, Javascript, Kotlin, Object Pascal (Delphi), Objective-C, PHP, Rust, Scala, SASS, Swift, Xojo

# 注释符&＃xff1a;Bourne shell and other UNIX shells, Cobra, Perl, Python, Ruby, Seed7, Windows PowerShell, PHP, R, Make, Maple, Elixir, Nim

那么&＃xff0c;**Python 为什么用“#”号作注释符&＃xff0c;而不是“//”呢&＃xff1f; **

这个问题恐怕没办法从解析的效率、符号的辨识度和输入的便利性等方面回答&＃xff0c;因为它们基本上没有区别。

我没有找到官方的解释&＃xff0c;但是从这些注释符的阵营中&＃xff0c;已经不难得出一个较为合理的解释&＃xff1a;

// 注释符基本上被 C 语言家族所用

# 注释符则基本上是被 Shell 和其它脚本语言所用

Python 在创造之初&＃xff0c;从 C 和 Shell 语言中借鉴了不少东西&＃xff0c;但它是一种脚本语言&＃xff0c;因此在注释符这个最为基础的语言要素上&＃xff0c;就偏向了脚本语言的传统。

在某些“类脚本语言”中&＃xff0c;比如 yaml、conf 和 ini 等格式的配置文件&＃xff0c;它们大多也是采用脚本语言的“#”号作为注释符。

所以&＃xff0c;Python 行内注释符的选择&＃xff0c;大概可以归结为一种历史原因&＃xff0c;即借鉴了 Shell 脚本语言的写法。

相比于行注释符的多样&＃xff0c;块注释符更加是让人眼花缭乱&＃xff1a;

大多数写法是我从未见过的&＃xff0c;有些甚至是难以忍受的&＃xff0c;槽点太多&＃xff01;

在这份表格里&＃xff0c;我们看不到 Python&＃xff0c;因为从严格意义上讲&＃xff0c;Python 并没有块注释符&＃xff01;

一般而言&＃xff0c;我们在连续的每行内容前面加“#”号&＃xff0c;达到块注释的效果。块注释被看作是多个行注释。

PEP-8 中是这么建议的&＃xff1a;

Each line of a block comment starts with a # and a single space (unless it is indented text inside the comment).

有人曾在 Twitter 上发问&＃xff0c;为什么 Python 没有块注释符&＃xff1f;

Guido 回复称&＃xff0c;可以将多行字符串用作块注释&＃xff1a;

Python 的多行字符串用三对单引号或双引号表示&＃xff0c;它还可以用作文档字符串(即Documentation Strings&＃xff0c;简写docstrings)。

但是&＃xff0c;将它当做多行注释符使用&＃xff0c;在语义上则有点怪怪的——它表示的是一段字符串&＃xff0c;虽然没有赋值给变量&＃xff0c;不会生成代码&＃xff0c;但是它并非语义上的注释。

由于脚本语言的特性&＃xff0c;它允许我们写一段“无根的字符串”&＃xff0c;在语法上没有问题&＃xff0c;也没有负作用(negative effects)&＃xff0c;但是&＃xff0c;如果把它作为注释使用&＃xff0c;这就是一种副作用(side effects)了。

从这点上考虑&＃xff0c;我虽然不反对有人把多行字符串写法用作块注释&＃xff0c;但是我会更推荐大家使用“#”号作注释。

另外&＃xff0c;对于无用的代码&＃xff0c;最好的做法就是直接删除&＃xff0c;如果后续发现有需要&＃xff0c;再回退修改。详细的多行注释尽量放在文档字符串中&＃xff0c;这样在核心代码中就会很少出现多行注释的情况了。

对于 Python 的注释符用法&＃xff0c;大家是怎么想的呢&＃xff1f;欢迎留言交流。

如果你觉得本文分析得不错&＃xff0c;那你应该会喜欢这些文章&＃xff1a;

写在最后&＃xff1a;本文属于“Python为什么”系列(Python猫出品)&＃xff0c;该系列主要关注 Python 的语法、设计和发展等话题&＃xff0c;以一个个“为什么”式的问题为切入点&＃xff0c;试着展现 Python 的迷人魅力。若你有其它感兴趣的话题&＃xff0c;欢迎填在《Python的十万个为什么&＃xff1f; 》里的调查问卷中。部分话题会推出视频版&＃xff0c;请在 B 站收看&＃xff0c;观看地址&＃xff1a;视频地址

公众号【Python猫】&＃xff0c; 本号连载优质的系列文章&＃xff0c;有Python为什么系列、喵星哲学猫系列、Python进阶系列、好书推荐系列、技术写作、优质英文推荐与翻译等等&＃xff0c;欢迎关注哦。