19、代码文档编写与工具使用

代码文档编写与工具使用

1. 代码文档中的重要关系与示例

1.1 依赖关系

在代码中，依赖关系十分重要。一个部分可能在逻辑上（通过继承或组合）、功能上（例如通过导入）或时间上（可能一个部分为另一个部分的正确运行执行设置）依赖于另一个部分。所有的依赖关系都应该进行文档记录。

1.2 模式关系

成为同一模式的一部分也是一种重要关系。设计模式越来越重要，它决定了各种机制的存在。如果一个类是某个模式实现的一部分，也应该对其进行文档记录。

1.3 示例的作用

尽管英文描述很有用，但几个示例是无可替代的。有些操作系统的唯一有用文档就是以示例的形式存在的。

1.4 示例代码

以下是一个来自 Rosetta Code 的中国剩余定理的 Python 实现示例：

"""Company boilerplate goes here.
Suppose n1, ..., nk are positive integers that are pairwise coprime. Then, for any 
given sequence of integers a1, ..., ak, there exists an integer x solving the following 
system of simultaneous congruences.
x ≡ a1 mod n1
x ≡ a2 mod n2
…
x ≡ ak mod nk
A full explanation of the theorem can b