1.2　代码注释与帮助文档

案例4　在代码中写注释

导语

注释的作用是对源代码的功能做补充说明，它是给源代码的阅读者（或开发者）看的，编译器在分析代码时不会扫描注释部分。也就是说，注释不会参与应用程序的执行。如果说程序代码是“给机器看的”，那么，注释就是“给人看的”。

Python代码的注释以字符“#”开头，紧随其后的一行文本会被识别为注释。开发人员应当养成给代码写注释的习惯，既方便自己，也方便他人。而且推荐的做法是：在字符“#”与注释内容之间至少留一个空格。就像这样

这样写，能提升注释内容的易读性，而且看起来也舒服。

另外，注释既可以单独写一行，也可以与代码语句处在同一行（需要写在代码之后，不然会连同代码也被注释掉）。例如

操作流程

步骤1：下面的代码声明了一个变量并初始化，随后还定义了一个函数。但本例的重点是练习注释的书写方法，所以，应该关注变量var1和函数Func1之前的注释内容。

步骤2：而在接下来的代码片段中，将看到，注释内容写在代码之后，与代码处在同一行。

上面代码声明了一个名为Demo的新类，__init__是类的构造函数，当类的案例初始化时会被调用。在构造函数中，为Demo类的案例（由参数self引用）设置了ver、pack、title三个动态属性。

案例5　设置代码文件的字符编码

导语

默认情况下，Python将以UTF-8编码格式来处理代码文件，因此多数时候无须刻意指定代码文件的字符编码。但是，在一些特殊的应用情景，可能需要为代码文件指定字符编码。

其实，用于设置文件编码的指令也是一行注释，只是它的格式必须匹配以下正则表达式：

即使用以下格式

此行注释比较特殊，必须出现在代码文件的第一行。如果出现在文件的第二行，那么第一行也只能是注释，例如：

总的来说，设置文件编码的注释必须写在所有程序代码之前。

操作流程

步骤1：指定代码文件使用UTF-8编码。在代码文件首行输入

步骤2：指定代码文件使用ASCII编码。

案例6　为代码对象撰写帮助文档

导语

帮助文档与注释不同。注释是不参与代码的编译和执行的，仅作为给代码阅读者的提示；而帮助文档是写进代码中的，用于告诉最终用户或者其他开发人员如何调用当前代码对象（包括模块、类、函数等）。而且，应用程序代码可以通过名为__doc__的特殊属性来访问帮助文档，但注释文本在代码中是无法访问的。

按照约定，紧跟在声明语句之后的第一个字符串表达式会被识别为该对象的帮助文档。另外，也可以直接将帮助文本赋值给对象的__doc__属性。

操作流程

步骤1：在代码文件的首行（或者在所有代码之前）输入的字符串表达式，即为当前模块的帮助文档。

一个代码文件即为模块，在文件的起始处的首个字符串表达式默认被赋值给模块的__doc__属性。因此，也可以在代码文件中直接给__doc__属性赋值。

设置模块级的帮助文档后，可通过__doc__属性来读取。

输出结果如下：

步骤2：声明一个Add函数，并为函数加上文档说明，介绍它的调用方法。

或者在编写完Add函数后，再通过__doc__属性来设置帮助文档。

步骤3：接下来定义一个cvt_bytes类，它包含两个静态方法。

上面代码中，＠staticmethod是一个装饰器，应用后表示tobytes和tostr两个方法是静态，即通过cvt_bytes类本身就能调用的方法，无须创建类案例。

步骤4：可以通过调用help函数来获取整个cvt_bytes类的成员列表，以及所关联的帮助文档。

输出结果如下：

其中，成员__dict__与__weakref__是从object类继承下来的。尽管在定义cvt_bytes类时没有明确指定它以object为基类，但object类是所有类型的基类，因此，自定义类默认也是以object为基类的。