5、Python编程：文档、模块与数据访问控制

Python编程：文档、模块与数据访问控制

1. Python代码文档化

Python是一种易于阅读的编程语言，有人甚至认为它具有自我文档化的特性。但在进行面向对象编程时，编写清晰总结每个对象和方法功能的API文档至关重要。保持文档的最新状态颇具挑战，最佳做法是将文档直接写进代码中。

1.1 文档字符串（Docstrings）

Python通过文档字符串支持代码文档化。每个类、函数或方法的头部，在定义行（以冒号结尾的行）之后的第一行可以是一个标准的Python字符串，这行字符串的缩进应与后续代码一致。

文档字符串是用单引号（’）或双引号（”）括起来的Python字符串。通常，文档字符串较长且跨多行（风格指南建议每行长度不超过80个字符），可以使用三引号（’‘’ 或 “”“）将其格式化为多行字符串。

文档字符串应清晰简洁地总结其所描述的类或方法的用途，解释那些使用方式不明显的参数，还可以包含API使用的简短示例，并注明API用户应注意的任何警告或问题。

以下是一个完整文档化的 Point 类示例：

import math

class Point:
    'Represents a point in two-dimensional geometric coordinates'
    def __init__(self, x=0, y=0):
        '''Initialize the position of a new point. The x and y 
           coordina