19、代码文档化：从基础到高级工具

代码文档化：从基础到高级工具

1. 代码关系与文档记录

在代码开发中，有两种重要的关系需要进行文档记录。

1.1 依赖关系

一个部分可能在逻辑上（通过继承或组合）、功能上（例如通过导入）或时间上（一个部分为另一个部分的正确运行执行必要的设置）依赖于另一个部分。所有的依赖关系都应该被记录下来。

1.2 模式关系

如果一个类是某个设计模式实现的一部分，也应该对其进行文档记录。设计模式在软件开发中变得越来越重要，它决定了各种机制的存在。

2. 示例的重要性

虽然英文描述很有用，但几个示例是无可替代的。有些操作系统的唯一有用文档就是以示例的形式存在的。下面是一个中国剩余定理的 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 be found at https://en.wikipedia.org/
w