《Python完全自学教程》免费在线连载2.2

2.2 注释

之所以要学习高级编程语言，而不学习机器语言，是因为高级编程语言“对人友好”。现在高级编程语言的演化方向也是“对人更友好”、“更节省开发者时间”。

如今的软件开发实践，也不再是纯粹的“个体劳动”，已经越来越“流水线化”——偶尔也会有报道某软件是某个人凭一己之力开发的，事实上如今的孤胆英雄也仅存在于文稿中，更多的是多人协作进行开发。既然如此，那么就要让写的程序更便于人“看懂”，为此要涉及到高级编程语言的变量、函数等的命名，以及代码的组织结构等等多方面问题，这些内容在本书后续内容中会逐步学习。本节先学习一种简单且非常重要的方法：写注释（ comment ）。

注释是程序的重要组成部分，良好的注释有助于增强程序的可读性、可维护性。注释是“给人看的”，所以，一定要用自然语言编写（至于用哪种自然语言，要根据项目的统一规定和人员的组成状况而定）。

以2.1节所创建的 hello.py 文件为例，在其中增加如下所示的内容：

print("Hello World")    # print a string.
print("Life is short. You need Python.")    # 打印一行英文字符。

所增加的内容就是注释，其中：

• #是英文状态下输入的注释开始符号，表示此符号之后的内容都是注释，直到本行结束。
• “ print a tring ”和“ 打印一行英文字符。 ”是注释的具体内容，此内容与 # 符号之间的空格不是强制的，有此空格更便于阅读。

如此形式的注释，也称为“行注释”——从注释符号开始到本行结束，都是注释。

在上面的示例中，一行注释使用的是英文，另一行是中文。然后调试上述代码，正常地显示了打印的结果（如图2-2-1所示），这说明 Python 解释器在执行此程序的时候，并没有受到所增加的注释影响——注释是给人看的，“机器不看”。

图2-2-1 调试增加注释后的程序

可能有的读者在调试上述代码的时候报错，比如类似下面的错误提示：

SyntaxError: Non-UTF-8 code starting with '\xb4' in file /Users/qiwsir/codes/hello.py on line 2, but no encoding declared; see http://python.org/dev/peps/pep-0263/ for details

这是字符编码所致，如果删除了程序中的中文注释，就会消除此错误——这是方法之一。由报错信息可知，此问题是所用 IDE 编码类型导致的。不论读者使用哪一款 IDE 软件，通常都应当将其编码设置为 UTF-8 （参见第4章4.1节）。图2-2-2所示是 VS Code 中显示的编码配置。所以，将 IDE 编码设置为 UTF-8 也是一种解决方法。

图2-2-2 VS Code 中设置 UTF-8 编码

还有一个方法，就是在文件的顶部声明使用 UTF-8 编码。

#coding:utf-8
print("Hello World")    # print a string.
print("Life is short. You need Python.")    # 打印一行英文字符。

新增 #coding:utf-8之后，调试此程序，就不再报错了。除了如上所示的写法之外，读者在其他资料中还会看到 # -*- coding:utf-8 -*- 和 #coding=utf-8 ，都是声明本文件使用 UTF-8 编码，如此即可在文件中使用中文等非英文字符。

符号 # 发起的注释，可以如前面那样，用在某行代码之后，用于注释该行；或者单独占据一行，多用于说明下面若干行代码的含义，如：

# This is my first Python program.
print("Hello World")

另外，在调试程序的时候，有可能要暂时不让计算机“看到”某些代码，也可以在该行代码前面加上 # ，将其暂时转换为注释，等需要的时候再转换回来。例如将 hello.py 文件中的代码修改为：

#coding:utf-8
print("Hello World")    # print a string.
# print("Life is short. You need Python.") 

此时调试该程序，则会只打印“ Hello World ”字样。

常用的 IDE 提供了实现多行“注释”以及取消的快捷操作。以 VS Code 为例，如图2-2-3所示，将第6、7、8、9三行代码选中之后，使用快捷键组合“ COMMAND + / ”（或“ CTRL + / ”），即可将选中的多行“注释”了（此处的“注释”是动词，或者说是“名词用作动词”，意思是“将多行代码变成了注释”。如图2-2-4所示）。这个组合键是“注释”和“取消注释”的切换键，即选中多个已注释的行之后，通过此组合键可以取消注释。

图2-2-3 选中多行

图2-2-4 实现对多行的注释

除了 # 发起的是单行注释之外，还有多行注释。如下代码所示，使用三对英文状态的下输入的双引号，能够实现多行注释，下面的代码依然是在 hello.py 中编辑，从第2行开始，输入了多行注释内容。

#coding:utf-8
"""
This is my first Python program.
I like it.
I am learning it myself.
"""

print("Hello World")    # print a string.
# print("Life is short. You need Python.")    

这种注释是针对本文件的，常称为“模块注释”（一个 .py文件，可以看做一个模块，关于模块的内容，参阅第11章11.1节）。

虽然代码的注释能够增强可读性，而且操作上简单易行，但是，对注释的争论向来没有消停，比如有的人说“好代码”不需要写注释（其本意是通过代码中变量、函数、类等命名以及恰当的代码组织实现高可读性），更多的争论围绕什么时候写注释、注释的内容是什么等展开。尽管对很多争论的话题都没有标准答案，但是在开发实践中，也逐渐达成了一些经验性的共识，比如：

注释内容不要重复代码。下面注释就不提倡。

print('Hello World')   # print hello world

不要用注释替代丑陋的变量命名。例如打算创建一个表示我已经出版的图书的列表（列表，是 Python 的一类内置对象，参阅第4章4.3节），如果用下面的方式：

# a list of books
a = ["机器学习数学基础", "Python完全自学手册", "数据准备和特征工程"]

虽然用注释的方式说明变量 a 的含义（关于变量，请参阅2.3节），但此注释实则是丑陋代码的遮羞布，丝毫无法改变所命名变量致使程序的可读性降低的本质。如果改为：

books = ["机器学习数学基础", "Python完全自学手册", "数据准备和特征工程"]

即使不用注释，代码的含义也一目了然。故首要的是写“好代码”，注释是对代码的辅助，而不要用注释替代晦涩的代码。

注释的用语简单明了，表达准确，且讲究文明礼貌。这是对开发者表达能力的基本要求。

★自学建议 编程是一类实践性非常强的工作，以本节介绍的“注释”为例，读者可以在网络上搜索到更多的相关内容，比如号称某些较知名机构的编程规范等，这些内容都可以用作自己工作实践的参考，但不能作为金科玉律。”